Iron Curtain — Design Documentation

Project: Rust-Native RTS Engine

Status: Pre-development (design phase)
Date: 2026-02-19
Codename: Iron Curtain
Author: David Krasnitsky

What This Is

A Rust-native RTS engine that supports OpenRA resource formats (.mix, .shp, .pal, YAML rules) and reimagines internals with modern architecture. Not a clone or port — a complementary project offering different tradeoffs (performance, modding, portability) with full OpenRA mod compatibility as the zero-cost migration path. OpenRA is an excellent project; IC explores what a clean-sheet Rust design can offer the same community.

Document Index

LLM feature overview (optional / experimental): See Experimental LLM Modes & Plans (BYOLLM) for a consolidated overview of planned LLM gameplay modes, creator tooling, and external-tool integrations. The project is fully designed to work without any LLM configured.

Key Architectural Invariants

These are non-negotiable across the entire project:

1. Simulation is pure and deterministic. No I/O, no floats, no network awareness. Takes orders, produces state. Period.
2. Network model is pluggable via trait. GameLoop<N: NetworkModel, I: InputSource> is generic over both network model and input source. The sim has zero imports from ic-net. They share only ic-protocol. Swapping lockstep for rollback touches zero sim code.
3. Modding is tiered. YAML (data) → Lua (scripting) → WASM (power). Each tier is optional and sandboxed.
4. Bevy as framework. ECS scheduling, rendering, asset pipeline, audio — Bevy handles infrastructure so we focus on game logic. Custom render passes and SIMD only where profiling justifies it.
5. Efficiency-first performance. Better algorithms, cache-friendly ECS, zero-allocation hot paths, simulation LOD, amortized work — THEN multi-core as a bonus layer. A 2-core laptop must run 500 units smoothly.
6. Real YAML, not MiniYAML. Standard serde_yaml with inheritance resolved at load time.
7. OpenRA compatibility is at the data/community layer, not the simulation layer. Same mods, same maps, shared server browser — but not bit-identical simulation.
8. Full resource compatibility with Red Alert and OpenRA. Every .mix, .shp, .pal, .aud, .oramap, and YAML rule file from the original game and OpenRA must load correctly. This is non-negotiable — the community’s existing work is sacred.
9. Engine core is game-agnostic. No game-specific enums, resource types, or unit categories in engine core. Positions are 3D (WorldPos { x, y, z }). System pipeline is registered per game module, not hardcoded.
10. Platform-agnostic by design. Input is abstracted behind InputSource trait. UI layout is responsive (adapts to screen size via ScreenClass). No raw std::fs — all assets go through Bevy’s asset system. Render quality is runtime-configurable.

Crate Structure Overview

iron-curtain/
├── ra-formats     # .mix, .shp, .pal, YAML parsing, MiniYAML converter (C&C-specific, keeps ra- prefix)
├── ic-protocol    # PlayerOrder, TimestampedOrder, OrderCodec trait (SHARED boundary)
├── ic-sim         # Deterministic simulation (Bevy FixedUpdate systems)
├── ic-net         # NetworkModel trait + implementations (Bevy plugins)
├── ic-render      # Isometric rendering, shaders, post-FX (Bevy plugin)
├── ic-ui          # Game chrome: sidebar, minimap, build queue (Bevy UI)
├── ic-editor      # SDK: scenario editor, asset studio, campaign editor, Game Master mode (D038+D040, Bevy app)
├── ic-audio       # .aud playback, EVA, music (Bevy audio plugin)
├── ic-script      # Lua + WASM mod runtimes
├── ic-ai          # Skirmish AI, mission scripting
├── ic-llm         # LLM mission/campaign generation, asset generation, adaptive difficulty
└── ic-game        # Top-level Bevy App, ties all game plugins together (NO editor code)

License

All files in src/ and research/ are licensed under CC BY-SA 4.0. Engine source code is licensed under GPL v3 with an explicit modding exception (D051).

Trademarks

Red Alert, Tiberian Dawn, Command & Conquer, and C&C are trademarks of Electronic Arts Inc. Iron Curtain is not affiliated with, endorsed by, or sponsored by Electronic Arts.

Foreword — Why I’m Building This

I’ve been a Red Alert fan since the first game came out. I was a kid, playing at a friend’s house over what we’d now call a “LAN” — two ancient computers connected with a cable. I was hooked. The cutscenes, the music, building a base and watching your stuff fight. I would literally go to any friend’s house that could run this game just to play it.

That game is the reason I wanted to learn how computers work. Someone, somewhere, built that. I wanted to know how.

Growing Up

I started programming at 12 — Pascal. Wrote little programs, thought it was amazing, and then looked at what it would actually take to make a game that looks and feels and plays real good. Yeah, that was going to take a while.

I went through a lot of jobs and technologies over the years. Network engineering, backend development, automations, cyber defense. I wrote Java for a while, then Python for many years. Each job taught me things I didn’t know I’d need later. I wasn’t chasing a goal — I was just building a career and getting better at making software.

Along the way I discovered Rust. It clicked. Most programming languages make you choose: either you get full control over your computer’s resources (but risk hard-to-find bugs and crashes), or you get safety (but give up performance). Rust gives you both. The language is designed so that entire categories of bugs — the kind that cause crashes, security holes, and impossible-to-reproduce errors — simply can’t happen. The compiler catches them before the program ever runs. You can write high-performance code and actually sleep at night.

I also found OpenRA around this time, and I was glad an open-source community had kept Red Alert alive for so long. I browsed through the C# codebase (I know C# well enough), enjoyed poking around the internals, but eventually real life pulled me away.

I did buy a Rust game dev book though. Took some Udemy courses. Played with prototypes. The idea of writing a game in Rust never quite left.

The Other Games That Mattered

I was a gamer my whole life, and a few games shaped how I think about making games, not just playing them.

Half-Life — I spent hours customizing levels and poking at its mechanics. Same for Deus Ex — pulling apart systems, seeing how things connected.

But the one that really got me was Operation Flashpoint: Cold War Crisis (now ArmA: Cold War Assault). OFP had a mission editor that was actually approachable. You could create scenarios in simple ways, dig through its resources and files, and build something that felt real. I spent more time editing missions, campaigns, and multiplayer scenarios for OFP than playing any other game. Recreating movie scenes, building tactical situations, making co-op missions for friends — that was my thing.

What OFP taught me is that the best games are the ones that give you tools and get out of your way. Games as platforms, not just products. That idea stuck with me for twenty years, and it’s a big part of why Iron Curtain works the way it does.

How This Actually Started

Over five years, Rust became my main language. I built backend systems, contributed to open-source projects, and got to the point where I could think in Rust the way I used to think in Python. The idea kept nagging: what if I tried writing a Red Alert engine in Rust?

Then, separately, I got into LLMs and AI agents. I was between jobs and decided to learn the tooling by building real projects with it. Honestly, I hated it at first. The LLM would generate a bunch of code, and I’d spend all my time reviewing and correcting it. It got credit for the fun part.

But the tools got better, and so did I. What changed is that they made it realistic to take on big, complex solo projects with proper architecture. Break everything down, make each piece testable, follow best practices throughout. The tooling caught up with what I already knew how to do.

This project didn’t start as an attempt to replace OpenRA. I just wanted to test new technology — see if Rust, Bevy, and LLM-assisted development could come together into something real. A proof of concept. A learning exercise. But the more I thought about the design, the more I realized it could actually serve the community. That’s when I decided to take it seriously.

This project is also a research opportunity. I want to take LLM-assisted coding to the next level — not just throw prompts at a model and ship whatever comes back. I’m a developer who needs to understand what code does. When code is generated, I do my best to read through it, understand every part, and verify it. I use the best models available to cross-check, document, and maintain a consistent code style so the codebase stays reviewable by humans.

There’s a compounding effect here: as the framework and architecture become more solid, the rules for how the LLM creates and modifies code become more focused and restricted. The design docs, the invariants, the crate boundaries — they all constrain what the LLM can do, which reduces the chance of serious errors. On top of that, I’m a firm believer in verifying code with tests and benchmarks. If it’s not tested, it doesn’t count.

If you’re curious about the actual methodology — how research is conducted, how decisions are made, how the human-agent relationship works in practice, and exactly how much work is behind these documents — see Chapter 14: Development Methodology, particularly the sections on the Research-Design-Refine cycle and Research Rigor. The short version: 62 design decisions, 32 standalone research documents, 20+ open-source codebases studied at the source code level, ~57,000 lines of structured documentation, 120+ commits of iterative refinement. None of it generated in a few prompts. All of it human-directed, human-reviewed, and human-committed.

What Bugged Me About the Alternatives

OpenRA is great for what it is. But I’ve felt the lag — not just in big battles, it’s random. Something feels off sometimes. The Remastered Collection has the same problem, which made me wonder if they went the C# route too — and it turns out they did. The original C++ engine runs as a DLL, but the networking and rendering layers are handled by a proprietary C# client. For me it comes down to raw performance: the original Red Alert was written in C, and it ran close to the hardware. C# doesn’t.

The Remastered Collection has the same performance issues. Modding is limited. Windows and Xbox only.

I kept thinking about what Rust brings to the table:

• Fast like C — runs close to the hardware, no garbage collector, predictable performance
• Safe — the compiler prevents the kinds of bugs that cause crashes and security vulnerabilities in other languages
• Built for multi-core — modern CPUs have many cores, and Rust makes it safe to use all of them without the concurrency bugs that plague other languages
• Here to stay — it’s in the Linux kernel, backed by every major tech company, and growing fast

What I Wanted to Build

Once I committed, the ideas came fast.

Bevy was the obvious engine choice. It’s the most popular community-driven Rust game engine, it uses a modern architecture that’s a natural fit for RTS games (where you need to efficiently manage thousands of units at once), and there’s a whole community of people working on it constantly. Building on top of Bevy means inheriting their progress instead of reinventing rendering, audio, and asset pipelines from scratch. And it means modders get access to a real modern rendering stack — imagine toggling between classic sprites and something with dynamic water, weather effects, proper lighting. Or just keeping it classic, but smooth.

Cross-engine compatibility — I wanted OpenRA players and Iron Curtain players to coexist. My background includes a lot of work translating between different systems, and the same principles apply here.

Switchable netcode — inspired by how CS2 does sub-tick processing and relay servers. If we pick the wrong networking model, or something better comes along, we should be able to swap it without touching the simulation code.

Community independence — the game should never die because someone turns off a server. Self-hosted everything. Federated workshop. No single point of failure.

Security done through architecture — not a kernel-level anti-cheat, but real defenses: order validation inside the simulation, signed replays, relay servers that own the clock. Stuff that comes from building backend systems and knowing how people cheat.

LLM-generated missions — this is the part that excites me most. What if you could describe a scenario in plain English and get a playable mission? Like OFP’s mission editor, but you just tell it what you want. The output is standard YAML and Lua, fully editable. You bring your own LLM — local or cloud, your choice. The game works perfectly without one, but for those who opt in: infinite content.

Where This Is Now

I put all of these ideas together and did a serious research phase to figure out what’s actually feasible. These design documents are the result. They cover architecture, networking, modding, security, performance, file format compatibility, cross-engine play, and a 36-month roadmap.

Every decision has a rationale. Every system has been thought through against the others. It’s designed to be built piece by piece, tested in isolation, and contributed to by anyone who cares to.

What started as “can I get this to work?” turned into “how do I make sure everything I build can serve the community?” That’s where I am now.

My goal is simple: make us fall in love again.

— David Krasnitsky, February 2026

What Iron Curtain Offers

Iron Curtain is a new open-source RTS engine built for the Command & Conquer community. It loads your existing Red Alert and OpenRA assets — maps, mods, sprites, music — and plays them on a modern engine designed for performance, modding, and competitive play. Ships with Red Alert and Tiberian Dawn, with more C&C titles and community-created games to follow.

This project is in design phase — no playable build exists yet. Everything below describes design targets, not shipped features.

For Players

• Smooth performance, even in large battles. No random stutters or micro-freezes. Rust has no garbage collector; Bevy’s ECS gives cache-friendly memory layout; zero allocation during gameplay. Target: 500 units smooth on a 2012 laptop, 2000+ on modern hardware.
• Multiplayer that doesn’t randomly break. No more matches silently falling out of sync with no explanation. Fixed-point integer math guarantees every player’s game stays in sync, and when something does go wrong, the engine pinpoints exactly what diverged.
• Play on any device. Windows, macOS, Linux, Steam Deck, browser (WASM), and mobile — all planned from day one via platform-agnostic architecture.
• Complete campaigns that flow. All original campaigns fully playable. Continuous mission flow (briefing → mission → debrief → next) — no exit-to-menu between levels.
• Branching campaigns. Your choices create different paths. Surviving units, veterancy, and equipment carry over between missions. Defeat is another branch, not a game over.
• Choose your own balance. Classic Westwood, OpenRA, or Remastered tuning — a lobby setting, not a mod. Tanya and Tesla coils feel as powerful as you remember, or as balanced as competitive play demands.
• Switchable pathfinding. Three movement models: Remastered (original feel), OpenRA (improved flow), IC Default (flowfield + ORCA-lite). Select per lobby or per scenario. Modders can ship custom pathfinding via WASM.
• Switchable render modes. Toggle Classic/HD/3D mid-game (F1 key, like the Remastered Collection). Different players can use different render modes in the same multiplayer game.
• Switchable AI opponents. Classic Westwood, OpenRA, or IC Default AI — selectable per AI slot. Two-axis difficulty (engine scaling + behavioral tuning). Mix different AI personalities and difficulties in the same match.
• Five ways to find a game. Direct IP, Among Us-style room codes, QR codes (LAN/streaming), server browser, ranked matchmaking queue — plus Discord/Steam deep links.
• Built-in voice and text chat. Push-to-talk voice (Opus codec, relay-forwarded), text chat with team/all/whisper/observer channels. Contextual ping system (8 types + ping wheel), chat wheel with auto-translated phrases, minimap drawing, tactical markers. Voice optionally recorded in replays (opt-in). Speaking indicators in lobby and in-game.
• Command console. Unified / command system — every GUI action has a console equivalent. Developer overlay, cvar system, tab completion with fuzzy matching. Hidden cheat codes (Cold War phrases) for single-player fun.
• Your data is yours. All player data stored locally in open SQLite files — queryable by any tool that speaks SQL. 24-word recovery phrase restores your identity on any machine, no account server needed. Full backup/restore via ic backup CLI. Optional Steam Cloud / GOG Galaxy sync for critical data.

For Competitive Players

• Ranked matchmaking. Glicko-2 ratings, seasonal rankings with Cold War military rank themes, 10 placement matches, optional per-faction ratings. Map veto system with anonymous opponent during selection.
• Player profiles. Avatar, title, achievement showcase, verified statistics, match history, friends list, community memberships. Reputation data is cryptographically signed — no fake stats.
• Architectural anti-cheat. Relay server owns the clock (blocks lag switches and speed hacks). Deterministic order validation (all clients agree on legality). No kernel drivers, no invasive monitoring — works on Linux and in browsers.
• Tamper-proof replays. Ed25519-signed replays and relay-certified match results. No disputes.
• Tournament mode. Caster view (no fog), player-perspective spectating, configurable broadcast delay (1–5 min), bracket integration, server-side replay archive.
• Sub-tick fairness. Orders processed in the order they happened, not the order packets arrived. Adapted from Counter-Strike 2’s sub-tick architecture.
• Train against yourself. AI mimics a specific player’s style from their replays. “Challenge My Weakness” mode targets your weakest skills for focused practice.
• Foreign replay import. Load and play back OpenRA and Remastered Collection replays directly. Convert to IC format for analysis. Automated behavioral regression testing against replay corpus.
• Fair-play match controls. Ready-check before match start. In-match voting — kick griefers, remake broken games, mutual draw — with anti-abuse protections (premade consolidation, army-value checks). Pause and surrender with ranked penalty framework.
• Disconnect handling. Grace period for brief disconnects, abandon penalties with escalating cooldowns, match voiding for early exits. Remaining teammates choose to play on (with AI substitute) or surrender.
• Spectator anti-coaching. In ranked team games, live spectators are locked to one team’s perspective — the relay won’t send opposing orders until the broadcast delay expires.

For Modders

• Your existing work carries over. Loads OpenRA YAML rules, maps, sprites, audio, and palettes directly. MiniYAML auto-converts at runtime. Migration tool included.
• Mod without programming. 80% of mods are YAML data files — change a number, save, done. Standard YAML means IDE autocompletion and validation work out of the box.
• Three tiers, no recompilation. YAML for data. Lua for scripting (missions, AI, abilities). WASM for engine-level mods (new mechanics, total conversions) in any language — sandboxed, near-native speed.
• Scenario editor. Full SDK with 30+ drag-and-drop modules across 8 categories: terrain painting, unit placement, visual trigger editor, reusable compositions (publishable to Workshop), layers with runtime show/hide, media & cinematics (video playback, cinematic sequences, dynamic mood-based music, ambient sound zones, EVA notifications with priority queuing). Campaign editor with visual graph and weighted random paths. Game Master mode for live scenario control. Simple and Advanced modes with onboarding profiles for veterans of other editors.
• Asset studio. Visual asset browser (XCC Mixer replacement), sprite/palette/terrain editors, bidirectional format conversion (SHP↔PNG, AUD↔WAV, VQA↔WebM), UI theme designer. Hot-reload bridge between editor and running game.
• Workshop for everything, not just mods. Publish individual music tracks, sprite sheets, voice packs, balance presets, UI themes, script libraries, maps, campaign chapters, or full mods — each independently versioned, licensed, and dependable. A mission pack can depend on a music pack and an HD sprite pack without bundling either.
• Auto-download on lobby join. Join a game → missing content downloads automatically via P2P (BitTorrent/WebTorrent). Lobby peers seed directly — fast and free. Auto-downloaded content cleans itself up after 30 days of non-use; frequently used content auto-promotes to permanent.
• Dependency resolution. Cargo-style semver ranges, lockfile with SHA-256 checksums, transitive resolution, conflict detection. ic mod tree shows your full dependency graph. ic mod audit checks license compatibility.
• Reusable script libraries. Publish shared Lua modules (AI behaviors, trigger templates, UI helpers) as Workshop resources. Other mods require() them as dependencies — composable ecosystem instead of copy-paste.
• CI/CD publishing. Headless CLI with scoped API tokens. Tag a release in git → CI validates, tests, and publishes to the Workshop automatically. Beta/release promotion channels.
• Federated and self-hostable. Official server, community mirrors, local directories, and Steam Workshop — all appear in one merged view. Offline bundles for LAN parties. No single point of failure.
• Creator tools. Reputation scores, badges (Verified, Prolific, Foundation), download analytics, collections, ratings & reviews, DMCA process with due process. LLM agents can discover and pull resources with author consent (ai_usage permission per resource).
• Hot-reload. Change YAML or Lua, see it in-game immediately. No restart.
• Console command extensibility. Register custom / commands via Lua or WASM — with typed arguments, tab completion, and permission levels. Publish reusable .iccmd command scripts to the Workshop.
• Mod profiles. Save a named set of mods + experience settings as a shareable YAML file. One SHA-256 fingerprint replaces per-mod version checking in lobbies. ic profile save/activate/inspect/diff CLI. Publish profiles to the Workshop as modpacks.

For Content Creators & Tournament Organizers

• Observer and casting tools. No-fog caster view, player-perspective spectating, configurable broadcast delay, signed replays.
• Creator recognition. Reputation scores, featured badges, optional tipping links — credit and visibility for modders and creators.
• Player analytics. Post-game stats, career pages, campaign dashboards. Every ranked match links to its replay.

For Community Leaders & Server Operators

• Self-hostable everything. Relay, matchmaking, and workshop servers are all self-hostable. Federated architecture — communities mirror each other’s content. Ed25519-signed credential records (not JWT) with transparency logs for server accountability. No single point of failure.
• Community governance. RFC process, community-elected representatives, self-hosting independence. The project can’t be killed by one organization.
• Observability. OTEL-based telemetry (metrics, traces, logs), pre-built Grafana dashboards for self-hosters. Zero-cost when disabled.

For Developers & Contributors

• Modern Rust on Bevy. No GC, memory safety, fearless concurrency. ECS scheduling, parallel queries, asset hot-reloading, large plugin ecosystem. 11 focused crates with clear boundaries.
• Clean sim/net separation. ic-sim and ic-net never import each other — only ic-protocol. Swap the network model without touching simulation code.
• Multi-game engine. Game-agnostic core. RA and TD are game modules via a GameModule trait. Pathfinding, spatial queries, rendering, fog — all pluggable per game.
• Standalone crates. ra-formats parses C&C formats independently. ic-sim runs headless for AI training or testing.

Nice-to-Haves

Interested specifically in the LLM-related gameplay/content/tooling plans? See Experimental LLM Modes & Plans (BYOLLM) for a consolidated BYOLLM overview (all experimental / optional).

• AI-generated missions and campaigns (BYOLLM). Describe a scenario, get a playable mission — or generate an entire branching campaign with recurring characters who evolve, betray, and die based on your choices. Choose a story style (C&C Classic, Realistic Military, Political Thriller, and more). World Domination mode: conquer a strategic map region by region with garrison management and faction dynamics. Each mission reacts to how you actually played — the LLM reads your battle report and adapts the next mission’s narrative, difficulty, and objectives. Mid-mission radar comms, RPG-style dialogue choices, and cinematic moments are all generated. Every output is standard YAML + Lua, fully playable without the LLM after creation. Built-in mission templates provide a fallback without any LLM at all. Bring your own LLM; the engine never requires one. Phase 7.
• AI-generated custom factions (BYOLLM). Describe a faction concept in plain English — “a guerrilla faction that relies on stealth, traps, and hit-and-run” — and the LLM generates a complete tech tree, unit roster, building roster, and unique mechanics as standard YAML. References Workshop sprite packs, sound packs, and weapon definitions (with author consent) to assemble factions with real assets from day one. Balance-validated against existing factions. Fully editable by hand, publishable to Workshop, playable in skirmish and custom games. Phase 7.
• LLM-enhanced AI (BYOLLM). Two modes: LlmOrchestratorAi wraps conventional AI with LLM strategic guidance, LlmPlayerAi lets the LLM play the game directly — designed for community entertainment streams (“GPT vs. Claude playing Red Alert”). Observable reasoning overlay for spectators. Neither mode allowed in ranked. Phase 7.
• LLM coaching (BYOLLM). Post-match analysis, personalized improvement suggestions, and adaptive briefings based on your play history. Phase 7.
• LLM Skill Library (BYOLLM). Persistent, semantically-indexed store of verified LLM outputs — AI strategies and generation patterns that improve over time. Verification-to-promotion pipeline ensures quality. Shareable via Workshop. Voyager-inspired lifelong learning. Phase 7.
• Dynamic weather. Real-time transitions (sunny → rain → storm), terrain effects (frozen water, mud), snow accumulation. Deterministic weather state machine.
• Advanced visuals for modders. Bevy’s wgpu stack gives modders access to bloom, dynamic lighting, GPU particles, shader effects, day/night, smooth zoom, and even full 3D rendering — while the base game stays classic isometric. Render modes are switchable mid-game (see above).
• Switchable UI themes. Classic, Remastered, or Modern look — YAML-driven, community themes via Workshop.
• Achievements. Per-game-module, mod-defined via YAML + Lua, Steam sync.
• Toggleable QoL. Every convenience (attack-move, health bars, range circles) individually toggleable. Experience profiles bundle 6 axes — balance + AI preset + pathfinding preset + QoL + UI theme + render mode: “Vanilla RA,” “OpenRA,” “Remastered,” or “Iron Curtain.”

How This Was Designed

The networking design alone studied 20+ open-source codebases, 4 EA GPL source releases, and multiple academic papers — all at the source code level. Every major subsystem went through the same process. 62 design decisions with rationale. 32 research documents. ~57,000 lines of documentation across 120+ commits.

📖 Read the full design documentation →

LLM / RAG Retrieval Index

This page is a retrieval-oriented map of the design docs for agentic LLM use (RAG, assistants, copilots, review bots).

For a human-facing overview of the project’s experimental LLM gameplay/content/tooling plans, see Experimental LLM Modes & Plans (BYOLLM).

It is not a replacement for the main docs. It exists to improve:

• retrieval precision
• token efficiency
• canonical-source selection
• conflict resolution across overlapping chapters

Purpose

The mdBook is written for humans first, but many questions (especially design reviews) are now answered by agents that retrieve chunks of documentation. This index defines:

• which documents are canonical for which topics
• which documents are supporting / illustrative
• how to chunk and rank content for lower token cost
• how to avoid mixing roadmap ideas with accepted decisions

Canonical Source Priority (Use This Order)

When multiple docs mention the same topic, agents should prefer sources in this order unless the user specifically asks for roadmap or UX examples:

1. Decision docs (src/decisions/09*/D0XX-*.md) — normative design choices, tradeoffs, accepted defaults. Each decision is now a standalone file (e.g., src/decisions/09b/D052-community-servers.md). The parent 09b-networking.md etc. are lightweight index pages.
2. Core architecture / netcode / modding / security / performance chapters (02–06, 10) — system-level design details and implementation constraints
3. Player Flow (17-PLAYER-FLOW.md) — UX flows, screen layouts, examples, mock UI
4. Roadmap (08-ROADMAP.md) — phase timing and sequencing (not normative runtime behavior)
5. Research docs (research/*.md) — prior art, evidence, input to decisions (not final policy by themselves)

If conflict exists between a decision doc and a non-decision doc, prefer the decision doc and call out the inconsistency.

Doc Roles (RAG Routing)

Topic-to-Canonical Source Map

Retrieval Rules (Token-Efficient Defaults)

Chunking Strategy

• Decision files are now one-per-decision — chunk at ###/#### level within each file
• Architecture and player-flow files are now one-per-subsystem/screen — chunk at ###/#### level within each file
• Include heading path metadata, e.g.:
  • decisions/09g/D065-tutorial.md > Layer 3 > Controls Walkthrough
• Include decision IDs detected in the chunk (e.g., D065, D068)
• Tag each chunk with doc class: decision, architecture, ux-flow, roadmap, research

Chunk Size

• Preferred: 300–900 tokens
• Allow larger chunks for code blocks/tables that lose meaning when split
• Overlap: 50–120 tokens

Ranking Heuristics

• Prefer decision docs for normative questions (“should”, “must”, “decided”)
• Prefer src/18-PROJECT-TRACKER.md + src/tracking/milestone-dependency-map.md for “what next?”, dependency-order, and implementation sequencing questions
• Prefer src/tracking/implementation-ticket-template.md when the user asks for implementer task breakdowns or ticket-ready work packages tied to G* steps
• Prefer src/tracking/external-code-project-bootstrap.md, src/tracking/external-project-agents-template.md, and src/tracking/source-code-index-template.md when the user asks how to start a separate code repo that should follow these design docs
• Prefer src/tracking/future-language-audit.md + src/tracking/deferral-wording-patterns.md for reviews of vague future wording, deferral placement, and North Star claim formatting
• Prefer src/tracking/testing-strategy.md for CI/CD pipeline definitions, test tier assignments, fuzz targets, performance benchmarks, and release criteria
• Prefer src/architecture/type-safety.md + src/16-CODING-STANDARDS.md § Type-Safety Coding Standards for newtype policy, deterministic collection bans, typestate patterns, and clippy configuration
• Prefer src/player-flow/*.md (individual screen files) for UI layout / screen wording questions — use the index in 17-PLAYER-FLOW.md to route to the right file
• Prefer 08-ROADMAP.md only for “when / phase” questions
• Prefer research docs only when the question is “why this prior art?” or “what did we learn from X?”

Conflict Handling

If retrieved chunks disagree:

1. Prefer the newer revision-noted decision text
2. Prefer decision docs over non-decision docs
3. Prefer security/netcode docs for trust/authority behavior
4. State the conflict explicitly and cite both locations

High-Cost Docs — Resolved

All previously identified high-cost files have been split into individually addressable units:

Retrieval pattern: Read the index page (~500–800 tokens) to identify which sub-file to load, then load only that sub-file (~2k–12k tokens). Never load the full original content unless doing a cross-cutting audit.

Decision Capsule Standard (Pointer)

For better RAG summaries and lower retrieval cost, add a short Decision Capsule near the top of each decision (or decision file).

Template:

• src/decisions/DECISION-CAPSULE-TEMPLATE.md

Capsules should summarize:

• decision
• status
• canonical scope
• defaults / non-goals
• affected docs
• revision note summary

This gives agents a cheap “first-pass answer” before pulling the full decision body.

Practical Query Tips (for Agents and Humans)

• Include decision IDs when known (D068 selective install, D065 tutorial)
• Include doc role keywords (decision, player flow, roadmap) to improve ranking
• For behavior + UI questions, retrieve both:
  • decision doc chunk (normative)
  • 17-PLAYER-FLOW.md chunk (surface/example)

Examples:

• D068 cutscene variant packs AI Enhanced presentation fingerprint
• D065 controls walkthrough touch phone tablet semantic prompts
• D008 sub-tick timestamp normalization relay canonical order

01 — Vision & Competitive Landscape

Project Vision

Build a Rust-native RTS engine that:

• Supports OpenRA resource formats (.mix, .shp, .pal, YAML rules)
• Reimagines internals with modern architecture (not a port)
• Explores different tradeoffs: performance, modding depth, portability, and multiplayer architecture
• Provides OpenRA mod compatibility as the zero-cost migration path
• Is game-agnostic at the engine layer — built for the C&C community but designed to power any classic RTS (D039). Ships with Red Alert (default) and Tiberian Dawn as built-in game modules; RA2, Tiberian Sun, and community-created games are future modules on the same engine (RA2 is a future community goal, not a scheduled deliverable)

Community Pain Points We Address

These are the most frequently reported frustrations from the C&C community — sourced from OpenRA’s issue tracker (135+ desync issues alone), competitive player feedback (15+ RAGL seasons), modder forums, and the Remastered Collection’s reception. Every architectural decision in this document traces back to at least one of these. This section exists so that anyone reading this document for the first time understands why the engine is designed the way it is.

Critical — For Players

1. Desyncs ruin multiplayer games. OpenRA has 135+ desync issues in its tracker. The sync report buffer is only 7 frames deep — when a desync occurs mid-game, diagnosis is often impossible. Players lose their game with no explanation. This is the single most-complained-about multiplayer issue. → IC answer: Per-tick state hashing follows the Spring Engine’s SyncDebugger approach — binary search identifies the exact tick and entity that diverged. Fixed-point math (no floats in sim — invariant #1) eliminates the most common source of cross-platform non-determinism. See 03-NETCODE.md for the full desync diagnosis design.

2. Random performance drops. Even at low unit counts, something “feels off” — micro-stutters from garbage collection pauses, unpredictable frame timing. In competitive play, a stutter during a crucial micro moment loses games. C#/.NET’s garbage collector is non-deterministic in timing. → IC answer: Rust has no garbage collector. Zero per-tick allocation is an invariant (not a goal — a rule). The efficiency pyramid (see 10-PERFORMANCE.md) prioritizes better algorithms and cache layout before reaching for threads. Target: 500-unit battles smooth on a 2-core 2012 laptop.

3. Campaigns are systematically incomplete. OpenRA’s multiplayer-first culture has left single-player campaigns unfinished across multiple supported games: Dune 2000 has only 1 of 3 campaigns playable, TD campaigns are also incomplete, and there’s no automatic mission progression — players exit to menu between missions. → IC answer: Campaign completeness is a first-class exit criterion for every shipped game module. Branching campaign graphs with persistent unit rosters, veterancy, and equipment carry-over (D021) go beyond completion to innovation. Continuous flow: briefing → mission → debrief → next mission, no menu breaks.

4. No competitive infrastructure. No ranked matchmaking, no automated anti-cheat, no signed replays. The competitive scene relies entirely on community-run CnCNet ladders and trust-based result reporting. → IC answer: Glicko-2 ranked matchmaking, relay-certified match results (signed by the relay server — fraud-proof), Ed25519-signed tamper-proof replays, tournament mode with configurable broadcast delay. See 01-VISION.md § Competitive Play and 06-SECURITY.md.

5. Balance debates fractured the community. OpenRA’s competitive rebalancing made iconic units feel less powerful — Tanya, MiGs, V2 rockets, Tesla coils all nerfed for tournament fairness. This was a valid competitive choice, but it became the only option. Players who preferred the original feel had no path forward. The community split over whether the game should feel like Red Alert or like a balanced esport. → IC answer: Switchable balance presets (D019) — classic EA values (default), OpenRA balance, Remastered balance, custom — are a lobby setting, not a total conversion. Choose your experience. No one’s preference invalidates anyone else’s.

6. Platform reach is limited. The Remastered Collection is Windows/Xbox only. OpenRA covers Windows, macOS, and Linux but not browser or mobile. There’s no way to play on a phone, in a browser, or on a Steam Deck without workarounds. → IC answer: Designed for Windows, macOS, Linux, Steam Deck, browser (WASM), and mobile from day one. Platform-agnostic architecture (invariant #10) — input abstracted behind traits, responsive UI, no raw filesystem access.

Critical — For Modders

7. Deep modding requires C#. OpenRA’s YAML system covers ~80% of modding, but anything beyond value tweaks — new mechanics, total conversions, custom AI — requires writing C# against a large codebase with a .NET build toolchain. This limits the modder pool to people comfortable with enterprise software development. → IC answer: Three tiers — YAML (data, 80% of mods), Lua (scripting, missions and abilities), WASM (engine-level, total conversions) — no recompilation ever (invariant #3). WASM accepts any language. The modding barrier drops from “learn C# and .NET” to “edit a YAML file.”

8. MiniYAML has no tooling. OpenRA’s custom data format has no IDE support, no schema validation, no linting, no standard parsing libraries. Every editor is a plain text editor. Typos and structural errors are discovered at runtime. → IC answer: Standard YAML with serde_yaml (D003). JSON Schema for validation. IDE autocompletion and error highlighting work out of the box with any YAML-aware editor.

9. No mod distribution system. Mods are shared via forum posts and manual file copying. There’s no in-game browser, no dependency management, no integrity verification, no one-click install. → IC answer: Workshop registry (D030) with in-game browser, auto-download on lobby join (CS:GO-style), semver dependencies, SHA-256 integrity, federated mirrors, Steam Workshop as optional source.

10. No hot-reload. Changing a YAML value requires restarting the game. Changing C# code requires recompiling the engine. Iteration speed for mod development is slow. → IC answer: YAML + Lua hot-reload during development. Change a value, see it in-game immediately. WASM mods reload without game restart.

Important — Structural

11. Single-threaded performance ceiling. OpenRA’s game loop is single-threaded (verified from source). There’s a hard ceiling on how many units can be simulated per tick, regardless of how many CPU cores are available. → IC answer: Bevy’s ECS scheduling enables parallel systems where profiling justifies it. But per the efficiency pyramid (D015), algorithmic improvements and cache layout come first — threading is the last optimization, not the first.

12. Scenario editor is terrain-only. OpenRA’s map editor handles terrain and actor placement but not mission logic — triggers, objectives, AI behavior, and scripting must be done in separate files by hand. → IC answer: The IC SDK (D038+D040) ships a full creative toolchain: visual trigger editor, drag-and-drop logic modules, campaign graph editor, Game Master mode, asset studio. Inspired by OFP/Arma 3 Eden — not just a map painter, a mission design environment.

These pain points are not criticisms of OpenRA — they’re structural consequences of technology choices made 18 years ago. OpenRA is a remarkable achievement. Iron Curtain exists because we believe the community deserves the next step.

Why This Deserves to Exist

Capabilities Beyond OpenRA and the Remastered Collection

New Capabilities Not Found Elsewhere

Branching Campaigns with Persistent State (D021)

Campaigns are directed graphs of missions, not linear sequences. Each mission can have multiple outcomes (“won with bridge intact” vs “won but bridge destroyed”) that lead to different next missions. Failure doesn’t end the campaign — defeat is another branch. Surviving units, veterancy, and equipment carry over between missions. Continuous flow: briefing → mission → debrief → next mission, no exit-to-menu between levels. Inspired by Operation Flashpoint.

Optional LLM-Generated Missions (BYOLLM — power-user feature)

For players who want more content: an optional in-game interface where players describe a scenario in natural language and receive a fully playable mission — map layout, objectives, enemy AI, triggers, briefing text. Generated content is standard YAML + Lua, fully editable and shareable. Requires the player to configure their own LLM provider (local or cloud) — the engine never ships or requires a specific model. Every feature works fully without an LLM configured.

Rendering: Classic First, Modding Possibilities Beyond

The core rendering goal is to faithfully reproduce the classic Red Alert isometric aesthetic — the same sprites, the same feel. HD sprite support is planned so modders can provide higher-resolution assets alongside the originals.

Because the engine builds on Bevy’s rendering stack (which includes a full 2D and 3D pipeline via wgpu), modders gain access to capabilities far beyond the classic look — if they choose to use them:

• Post-processing: bloom, color grading, screen-space reflections on water
• Dynamic lighting: explosions illuminate surroundings, day/night cycles
• GPU particle systems: smoke, fire, debris, weather (rain, snow, sandstorm, fog, blizzard)
• Dynamic weather: real-time transitions (sunny → overcast → rain → storm), snow accumulation on terrain, puddle formation, seasonal effects — terrain textures respond to weather via palette tinting, overlay sprites, or shader blending (D022)
• Shader effects: chrono-shift shimmer, iron curtain glow, tesla arcs, nuclear flash
• Smooth camera: sub-pixel rendering, cinematic replay camera, smooth zoom
• 3D rendering: a Tier 3 (WASM) mod can replace the sprite renderer entirely with 3D models while the simulation stays unchanged

These are modding possibilities enabled by the engine’s architecture, not development goals for the base game. The base game ships with the classic isometric aesthetic. Visual enhancements are content that modders and the community build on top.

Scenario Editor & Asset Studio (D038 + D040)

OpenRA’s map editor is a standalone terrain/actor tool. The IC SDK ships a full creative toolchain as a separate application from the game — not just terrain/unit placement, but full mission logic: visual triggers with countdown/timeout timers, waypoints, drag-and-drop modules (wave spawner, patrol route, guard position, reinforcements, objectives), compositions (reusable prefabs), Probability of Presence per entity for replayability, layers, and a Game Master mode for live scenario manipulation. The SDK also includes an asset studio (D040) for browsing, editing, and generating game resources — sprites, palettes, terrain, chrome/UI themes — with optional LLM-assisted generation for non-artists. Inspired by Operation Flashpoint’s mission editor, Arma 3’s Eden Editor, and Bethesda’s Creation Kit.

Architectural Differences from OpenRA

OpenRA is a mature, actively maintained project with 18 years of community investment. These are genuine architectural differences, not criticisms:

What Makes People Actually Switch

1. Better performance — visible: bigger maps, more units, no stutters
2. Campaigns that flow — branching paths, persistent units, no menu between missions, failure continues the story
3. Better modding — WASM scripting, SDK with scenario editor & asset studio, hot reload
4. Competitive infrastructure — ranked matchmaking, anti-cheat, tournaments, signed replays — OpenRA has none of this
5. Player analytics — post-game stats, career page, campaign dashboard with roster graphs — your match history is queryable data, not a forgotten replay folder
6. Better multiplayer — desync debugging, smoother netcode, relay server
7. Runs everywhere — browser via WASM, mobile, Steam Deck natively
8. OpenRA mod compatibility — existing community migrates without losing work
9. Workshop with auto-download — join a game, missing mods download automatically (CS:GO-style); no manual file hunting
10. Creator recognition — reputation scores, featured badges, optional tipping — modders get credit and visibility
11. Achievement system — per-game-module achievements stored locally, mod-defined achievements via YAML + Lua, Steam sync for Steam builds
12. Optional LLM enhancements (BYOLLM) — bring your own LLM for generated missions, adaptive briefings, coaching suggestions — a quiet power-user feature, not a headline

Item 8 is the linchpin. If existing mods just work, migration cost drops to near zero.

Competitive Play

Red Alert has a dedicated competitive community (primarily through OpenRA and CnCNet). CnCNet provides community ladders and tournament infrastructure, but there’s no integrated ranked system, no automated anti-cheat, and desyncs remain a persistent issue (135+ tracked in OpenRA’s issue tracker). This is a significant opportunity. IC’s CommunityBridge will integrate with both OpenRA’s and CnCNet’s game browsers (shared discovery, separate gameplay) so the C&C community stays unified.

Ranked Matchmaking

• Rating system: Glicko-2 (improvement over Elo — accounts for rating volatility and inactivity, used by Lichess, FIDE, many modern games)
• Seasons: 3-month ranked seasons with placement matches (10 games), YAML-configurable tier system (D055 — Cold War military ranks for RA: Conscript → Supreme Commander, 7+2 tiers × 3 divisions), end-of-season rewards
• Queues: 1v1 (primary), 2v2 (team), FFA (experimental). Separate ratings per queue
• Map pool: Curated competitive map pool per season, community-nominated and committee-voted. Ranked games use pool maps only
• Balance preset locked: Ranked play uses a fixed balance preset per season (prevents mid-season rule changes from invalidating results)
• Matchmaking server: Lightweight Rust service, same infra pattern as tracking/relay servers (containerized, self-hostable for community leagues)

Leaderboards

• Global, per-faction, per-map, per-game-module (RA1, TD, etc.)
• Public player profiles: rating history, win rate, faction preference, match history
• Replay links on every match entry — any ranked game is reviewable

Tournament Support

• Observer mode: Spectators connect to relay server and receive tick orders with configurable delay
  • No fog — for casters (sees everything)
  • Player fog — fair spectating (sees what one player sees)
  • Broadcast delay — 1-5 minute configurable delay to prevent stream sniping
• Bracket integration: Tournament organizers can set up brackets via API; match results auto-report
• Relay-certified results: Every ranked and tournament match produces a CertifiedMatchResult signed by the relay server (see 06-SECURITY.md). No result disputes.
• Replay archive: All ranked/tournament replays stored server-side for post-match analysis and community review

Anti-Cheat (Architectural, Not Intrusive)

Our anti-cheat emerges from the architecture — not from kernel drivers or invasive monitoring:

Philosophy: No kernel-level anti-cheat (no Vanguard/EAC). We’re open-source and cross-platform — intrusive anti-cheat contradicts our values and doesn’t work on Linux/WASM. We accept that lockstep has inherent maphack risk in P2P modes. The fog-authoritative server is the real answer for high-stakes play.

Performance as Competitive Advantage

Competitive play demands rock-solid performance — stutters during a crucial micro moment lose games:

Competitive Landscape

Active Projects

OpenRA (C#) — The community standard

• 14.8k GitHub stars, actively maintained, 18 years of community investment
• Latest release: 20250330 (March 2025) — new map editor, HD asset support, post-processing
• Mature community, mod ecosystem, server infrastructure — the project that proved open-source C&C is viable
• Multiplayer-first focus — single-player campaigns often incomplete (Dune 2000: only 1 of 3 campaigns fully playable; TD campaign also incomplete)
• SDK supports non-Westwood games (KKND, Swarm Assault, Hard Vacuum, Dune II remake) — validates our multi-game extensibility approach (D018)

Vanilla Conquer (C++)

• Cross-platform builds of actual EA source code
• Not reimagination — just making original compile on modern systems
• Useful reference for original engine behavior

Chrono Divide (TypeScript)

• Red Alert 2 running in browser, working multiplayer
• Proof that browser-based RTS is viable
• Study their architecture for WASM target

Dead/Archived Projects (lessons learned)

Chronoshift (C++) — Archived July 2020

• Binary-level reimplementation attempt, only English 3.03 beta patch
• Never reached playable state
• Lesson: 1:1 binary compatibility is a dead end

OpenRedAlert (C++)

• Based on ancient FreeCNC/FreeRA, barely maintained
• Lesson: Building on old foundations doesn’t work long-term

Key Finding

No Rust-based Red Alert or OpenRA ports exist. The field is completely open.

EA Source Release (February 2025)

EA released original Red Alert source code under GPL v3. Benefits:

• Understand exactly how original game logic works (damage, pathfinding, AI)
• Verify Rust implementation against original behavior
• Combined with OpenRA’s 17 years of refinements: “how it originally worked” + “how it should work”

Repository: https://github.com/electronicarts/CnC_Red_Alert

Reference Projects

These are the projects we actively study. Each serves a different purpose — do not treat them as interchangeable.

OpenRA — https://github.com/OpenRA/OpenRA

What to study:

• Source code: Trait/component architecture, how they solved the same problems we’ll face (fog of war, build queues, harvester AI, naval combat). Our ECS component model maps directly from their traits.
• Issue tracker: Community pain points surface here. Recurring complaints = design opportunities for us. Pay attention to issues tagged with performance, pathfinding, modding, and multiplayer.
• UX/UI patterns: OpenRA has 17 years of UI iteration. Their command interface (attack-move, force-fire, waypoints, control groups, rally points) is excellent. Adopt their UX patterns for player interaction.
• Mod ecosystem: Understand what modders actually build so our modding tiers serve real needs.

What NOT to copy:

• Unit balance. OpenRA deliberately rebalances units away from the original game toward competitive multiplayer fairness. This makes iconic units feel underwhelming (see Gameplay Philosophy below). We default to classic RA balance. This pattern repeats across every game they support — Dune 2000 units are also rebalanced away from originals.
• Simulation internals bug-for-bug. We’re not bit-identical — we’re better-algorithms-identical.
• Campaign neglect. OpenRA’s multiplayer-first culture has left single-player campaigns systematically incomplete across all supported games. Dune 2000 has only 1 of 3 campaigns playable; TD campaigns are also incomplete; there’s no automatic mission progression (players exit to menu between missions). Campaign completeness is a first-class goal for us — every shipped game module must have all original campaigns fully playable with continuous flow (D021). Beyond completeness, our campaign graph system enables what OpenRA can’t: branching outcomes (different mission endings lead to different next missions), persistent unit rosters (surviving units carry forward with veterancy), and failure that continues the story instead of forcing a restart — inspired by Operation Flashpoint.

EA Red Alert Source — https://github.com/electronicarts/CnC_Red_Alert

What to study:

• Exact gameplay values. Damage tables, weapon ranges, unit speeds, fire rates, armor multipliers. This is the canonical source for “how Red Alert actually plays.” When OpenRA and EA source disagree on a value, EA source wins for our classic preset.
• Order processing. The OutList/DoList pattern maps directly to our PlayerOrder → TickOrders → apply_tick() architecture.
• Integer math patterns. Original RA uses integer math throughout for determinism — validates our fixed-point approach.
• AI behavior. How the original skirmish AI makes decisions, builds bases, attacks. Reference for ic-ai.

Caution: The codebase is 1990s C++ — tangled, global state everywhere, no tests. Extract knowledge, don’t port patterns.

EA Remastered Collection — https://github.com/electronicarts/CnC_Remastered_Collection

What to study:

• UI/UX design. The Remastered Collection has the best UI/UX of any C&C game. Clean, uncluttered, scales well to modern resolutions. This is our gold standard for UI layout and information density. Where OpenRA sometimes overwhelms with GUI elements, Remastered gets the density right.
• HD asset pipeline. How they upscaled and re-rendered classic assets while preserving the feel. Relevant for our rendering pipeline.
• Sidebar design. Classic sidebar with modern polish — study how they balanced information vs screen real estate.

EA Tiberian Dawn Source — https://github.com/electronicarts/CnC_Tiberian_Dawn

What to study:

• Shared C&C engine lineage. TD and RA share engine code. Cross-referencing both clarifies ambiguous behavior in either.
• Game module reference. When we build the Tiberian Dawn game module (D018), this is the authoritative source for TD-specific logic.
• Format compatibility. TD .mix files, terrain, and sprites share formats with RA — validation data for ra-formats.

Chrono Divide — (TypeScript, browser-based RA2)

What to study:

• Architecture reference for our WASM/browser target
• Proof that browser-based RTS with real multiplayer is viable

Gameplay Philosophy

Classic Feel, Modern UX

Iron Curtain’s default gameplay targets the original Red Alert experience, not OpenRA’s rebalanced version. This is a deliberate choice:

• Units should feel powerful and distinct. Tanya kills soldiers from range, fast, and doesn’t die easily — she’s a special operative, not a fragile glass cannon. MiG attacks should be devastating. V2 rockets should be terrifying. Tesla coils should fry anything that comes close. If a unit was iconic in the original game, it should feel iconic here.
• OpenRA’s competitive rebalancing makes units more “fair” for tournament play but can dilute the personality of iconic units. That’s a valid design choice for competitive players, but it’s not our default.
• OpenRA’s UX/UI innovations are genuinely excellent and we adopt them: attack-move, waypoint queuing, production queues, control group management, minimap interactions, build radius visualization. The Remastered Collection’s UI density and layout is our gold standard for visual design.

Switchable Balance Presets (D019)

Because reasonable people disagree on balance, the engine supports balance presets — switchable sets of unit values loaded from YAML at game start:

Presets are just YAML files in rules/presets/. Switching preset = loading a different set of unit/weapon/structure YAML. No code changes, no mod required. The lobby UI exposes preset selection.

This is not a modding feature — it’s a first-class game option. “Classic” vs “OpenRA” balance is a settings toggle, not a total conversion.

Toggleable QoL Features (D033)

Beyond balance, every quality-of-life improvement added by OpenRA or the Remastered Collection is individually toggleable: attack-move, waypoint queuing, multi-queue production, health bar visibility, range circles, guard command, and dozens more. Built-in presets group these into coherent experience profiles:

Select a profile, then override any individual setting. Want classic balance with OpenRA’s attack-move but without build radius circles? Done. Good defaults, full customization.

See src/decisions/09d/D019-balance-presets.md and src/decisions/09d/D033-qol-presets.md, and D032 in src/decisions/09c-modding.md.

Timing Assessment

• EA source just released (fresh community interest)
• Rust gamedev ecosystem mature (wgpu stable, ECS crates proven)
• No competition in Rust RTS space
• OpenRA showing architectural age despite active development
• WASM/browser gaming increasingly viable
• Multiple EA source releases provide unprecedented reference material

Verdict: Window of opportunity is open now.

02 — Core Architecture

Keywords: architecture, crate boundaries, ic-sim, ic-net, ic-protocol, GameLoop<N, I>, NetworkModel, InputSource, deterministic simulation, Bevy, platform-agnostic design, game modules

Decision: Bevy

Rationale (revised — see D002 in decisions/09a-foundation.md):

• ECS is our architecture — Bevy gives it to us with scheduling, queries, and parallel system execution out of the box
• Saves 2–4 months of engine plumbing (windowing, asset pipeline, audio, rendering scaffolding)
• Plugin system maps naturally to pluggable networking (NetworkModel as a Bevy plugin)
• Bevy’s 2D rendering pipeline handles classic isometric sprites; the 3D pipeline is available passively for modders (see “3D Rendering as a Mod”)
• wgpu is Bevy’s backend — we still get low-level control via custom render passes where profiling justifies it
• Breaking API changes are manageable: pin Bevy version per development phase, upgrade between phases

Bevy provides:

Simulation / Render Split (Critical Architecture)

The simulation and renderer are completely decoupled from day one.

┌─────────────────────────────────────────────┐
│             GameLoop<N, I>                  │
│                                             │
│  Input(I) → Network(N) → Sim (tick) → Render│
│                                             │
│  Sim runs at fixed tick rate (e.g., 15/sec) │
│  Renderer interpolates between sim states   │
│  Renderer can run at any FPS independently  │
└─────────────────────────────────────────────┘

Simulation Properties

• Deterministic: Same inputs → identical outputs on every platform
• Pure: No I/O, no floats in game logic, no network awareness
• Fixed-point math: i32/i64 with known scale (never f32/f64 in sim)
• Snapshottable: Full state serializable for replays, save games, desync debugging, rollback, campaign state persistence (D021)
• Headless-capable: Can run without renderer (dedicated servers, AI training, automated testing)
• Library-first: ic-sim is a Rust library crate usable by external projects — not just an internal dependency of ic-game

External Sim API (Bot Development & Research)

ic-sim is explicitly designed as a public library for external consumers: bot developers, AI researchers, tournament automation, and testing infrastructure. The sim’s purity (no I/O, no rendering, no network awareness) makes it naturally embeddable.

#![allow(unused)]
fn main() {
// External bot developer's Cargo.toml:
// [dependencies]
// ic-sim = "0.x"
// ic-protocol = "0.x"

use ic_sim::{Simulation, SimConfig};
use ic_protocol::{PlayerOrder, TimestampedOrder};

// Create a headless game
let config = SimConfig::from_yaml("rules.yaml")?;
let mut sim = Simulation::new(config, map, players, seed);

// Game loop: inject orders, step, read state
loop {
    let state = sim.query_state();  // read visible game state
    let orders = my_bot.decide(&state);  // bot logic
    sim.inject_orders(&orders);  // submit orders for this tick
    sim.step();  // advance one tick
    if sim.is_finished() { break; }
}
}

Use cases:

• AI bot tournaments: Run headless matches between community-submitted bots. Same pattern as BWAPI’s SSCAIT (StarCraft) and Chrono Divide’s @chronodivide/game-api. The Workshop hosts bot leaderboards; ic mod test provides headless match execution (see 04-MODDING.md).
• Academic research: Reinforcement learning, multi-agent systems, game balance analysis. Researchers embed ic-sim in their training harness without pulling in rendering or networking.
• Automated testing: CI pipelines create deterministic game scenarios, inject specific order sequences, and assert on outcomes. Already used internally for regression testing.
• Replay analysis tools: Third-party tools load replay files and step through the sim to extract statistics, generate heatmaps, or compute player metrics.

API stability: The external sim API surface (Simulation::new, step, inject_orders, query_state, snapshot, restore) follows the same versioning guarantees as the mod API (see 04-MODDING.md § “Mod API Versioning & Stability”). Breaking changes require a major version bump with migration guide.

Distinction from AiStrategy trait: The AiStrategy trait (D041) is for in-engine AI that runs inside the sim’s tick loop as a WASM sandbox. The external sim API is for out-of-process consumers that drive the sim from the outside. Both are valid — AiStrategy has lower latency (no serialization boundary), the external API has more flexibility (any language, any tooling, full process isolation).

Phase: The external API surface crystallizes in Phase 2 when the sim is functional. Bot tournament infrastructure ships in Phase 4-5. Formal API stability guarantees begin when ic-sim reaches 1.0.

Simulation Core Types

#![allow(unused)]
fn main() {
/// All sim-layer coordinates use fixed-point
pub type SimCoord = i32;  // 1 unit = 1/SCALE of a cell (see P002)

/// Position is 3D-aware from day one.
/// RA1 game module sets z = 0 everywhere (flat isometric).
/// RA2/TS game module uses z for terrain elevation, bridges, aircraft altitude.
pub struct WorldPos {
    pub x: SimCoord,
    pub y: SimCoord,
    pub z: SimCoord,  // 0 for flat games (RA1), meaningful for elevated terrain (RA2/TS)
}

/// Cell position on a discrete grid — convenience type for grid-based game modules.
/// NOT an engine-core requirement. Grid-based games (RA1, RA2, TS, TD, D2K) use CellPos
/// as their spatial primitive. Continuous-space game modules work with WorldPos directly.
/// The engine core operates on WorldPos; CellPos is a game-module-level concept.
pub struct CellPos {
    pub x: i32,
    pub y: i32,
    pub z: i32,  // layer / elevation level (0 for RA1)
}

/// The sim is a pure function: state + orders → new state
pub struct Simulation {
    world: World,          // ECS world (all entities + components)
    tick: u64,             // Current tick number
    rng: DeterministicRng, // Seeded, reproducible RNG
}

impl Simulation {
    /// THE critical function. Pure, deterministic, no I/O.
    pub fn apply_tick(&mut self, orders: &TickOrders) {
        // 1. Apply orders (sorted by sub-tick timestamp)
        for (player, order, timestamp) in orders.chronological() {
            self.execute_order(player, order);
        }
        // 2. Run systems: movement, combat, harvesting, AI, production
        self.run_systems();
        // 3. Advance tick
        self.tick += 1;
    }

    /// Snapshot for rollback / desync debugging / save games.
    /// Uses crash-safe serialization: payload written first, header
    /// updated atomically after fsync (Fossilize pattern — see D010).
    pub fn snapshot(&self) -> SimSnapshot { /* serialize everything */ }
    pub fn restore(&mut self, snap: &SimSnapshot) { /* deserialize */ }

    /// Delta snapshot — encodes only components that changed since
    /// `baseline`. ~10x smaller than full snapshot for typical gameplay.
    /// Used for autosave, reconnection state transfer, and replay
    /// keyframes. See D010 and `10-PERFORMANCE.md` § Delta Encoding.
    pub fn delta_snapshot(&self, baseline: &SimSnapshot) -> DeltaSnapshot {
        /* property-level diff — only changed components serialized */
    }
    pub fn apply_delta(&mut self, delta: &DeltaSnapshot) {
        /* merge delta into current state */
    }

    /// Hash for desync detection
    pub fn state_hash(&self) -> u64 { /* hash critical state */ }

    /// Surgical correction for cross-engine reconciliation
    pub fn apply_correction(&mut self, correction: &EntityCorrection) {
        // Directly set an entity's field — only used by reconciler
    }
}
}

Order Validation (inside sim, deterministic)

#![allow(unused)]
fn main() {
impl Simulation {
    fn execute_order(&mut self, player: PlayerId, order: &PlayerOrder) {
        match self.validate_order(player, order) {
            OrderValidity::Valid => self.apply_order(player, order),
            OrderValidity::Rejected(reason) => {
                self.record_suspicious_activity(player, reason);
                // All honest clients also reject → stays in sync
            }
        }
    }
    
    fn validate_order(&self, player: PlayerId, order: &PlayerOrder) -> OrderValidity {
        // Every order type validated: ownership, affordability, prerequisites, placement
        // This is deterministic — all clients agree on what to reject
    }
}
}

ECS Design

ECS is a natural fit for RTS: hundreds of units with composable behaviors.

External Entity Identity

Bevy’s Entity IDs are internal — they can be recycled, and their numeric value is meaningless across save/load or network boundaries. Any external-facing system (replay files, Lua scripting, observer UI, debug tools) needs a stable entity identifier.

IC uses generational unit tags — a pattern proven by SC2’s unit tag system (see research/blizzard-github-analysis.md § Part 1) and common in ECS engines:

#![allow(unused)]
fn main() {
#[derive(Clone, Copy, Hash, Eq, PartialEq, Serialize, Deserialize)]
pub struct UnitTag {
    pub index: u16,     // slot in a fixed-size pool
    pub generation: u16, // incremented each time the slot is reused
}
}

• Index identifies the pool slot. Pool size is bounded by the game module’s max entity count (RA1: 2048 units + structures).
• Generation disambiguates reuse. If a unit dies and a new unit takes the same slot, the new unit has a higher generation. Stale references (e.g., an attack order targeting a dead unit) are detected by comparing generations.
• Replay and Lua stable: UnitTag values are deterministic — same game produces the same tags. Replay analysis can track a unit across its entire lifetime. Lua scripts reference units by UnitTag, never by Bevy Entity.
• Network-safe: UnitTag is 4 bytes, cheap to include in PlayerOrder. Bevy Entity is never serialized into orders or replays.

A UnitPool resource maps UnitTag ↔ Entity and manages slot allocation/recycling. All public-facing APIs (Simulation::query_unit(), order validation, Lua bindings) use UnitTag; Bevy Entity is an internal implementation detail.

Component Model (mirrors OpenRA Traits)

OpenRA’s “traits” are effectively components. Map them directly. The table below shows the RA1 game module’s default components. Other game modules (RA2, TD) register additional components — the ECS is open for extension without modifying the engine core.

OpenRA vocabulary compatibility (D023): OpenRA trait names are accepted as YAML aliases. Armament and combat both resolve to the same component. This means existing OpenRA YAML definitions load without renaming.

Canonical enum names (D027): Locomotor types (Foot, Wheeled, Tracked, Float, Fly), armor types (None, Light, Medium, Heavy, Wood, Concrete), target types, damage states, and stances match OpenRA’s names exactly. Versus tables and weapon definitions copy-paste without translation.

| OpenRA Trait | ECS Component | Purpose | | Health | Health { current: i32, max: i32 } | Hit points | | Mobile | Mobile { speed: i32, locomotor: LocomotorType } | Can move | | Attackable | Attackable { armor: ArmorType } | Can be damaged | | Armament | Armament { weapon: WeaponId, cooldown: u32 } | Can attack | | Building | Building { footprint: FootprintId } | Occupies cells (footprint shapes stored in a shared FootprintTable resource, indexed by ID — zero per-entity heap allocation) | | Buildable | Buildable { cost: i32, time: u32, prereqs: Vec<StructId> } | Can be built | | Selectable | Selectable { bounds: Rect, priority: u8 } | Player can select | | Harvester | Harvester { capacity: i32, resource: ResourceType } | Gathers ore | | Producible | Producible { queue: QueueType } | Produced from building |

These 9 components are the core set. The full RA1 game module registers ~50 additional components for gameplay systems (power, transport, capture, stealth, veterancy, etc.). See Extended Gameplay Systems below for the complete component catalog. The component table in AGENTS.md lists only the core set as a quick reference.

Component group toggling (validated by Minecraft Bedrock): Bedrock’s entity system uses “component groups” — named bundles of components that can be added or removed by game events (e.g., minecraft:angry adds AttackNearest + SpeedBoost when a wolf is provoked). This is directly analogous to IC’s condition system (D028): a condition like “prone” or “low_power” grants/revokes a set of component modifiers. Bedrock’s JSON event system ("add": { "component_groups": [...] }) validates that event-driven component toggling scales to thousands of entity types and is intuitive for data-driven modding. See research/mojang-wube-modding-analysis.md § Bedrock.

System Execution Order (deterministic, configurable per game module)

The RA1 game module registers this system execution order:

Per tick:
  1.  apply_orders()          — Process all player commands (move, attack, build, sell, deploy, guard, etc.)
  2.  power_system()          — Recalculate player power balance, apply/remove outage penalties
  3.  production_system()     — Advance build queues, deduct costs, spawn completed units
  4.  harvester_system()      — Gather ore, navigate to refinery, deliver resources
  5.  docking_system()        — Manage dock queues (refinery, helipad, repair pad)
  6.  support_power_system()  — Advance superweapon charge timers
  7.  movement_system()       — Move all mobile entities (includes sub-cell for infantry)
  8.  crush_system()          — Check vehicle-over-infantry crush collisions
  9.  mine_system()           — Check mine trigger contacts
  10. combat_system()         — Target acquisition, fire weapons, create projectile entities
  11. projectile_system()     — Advance projectiles, check hits, apply warheads (Versus table + modifiers)
  12. capture_system()        — Advance engineer capture progress
  13. cloak_system()          — Update cloak/detection states, reveal-on-fire cooldowns
  14. condition_system()      — Evaluate condition grants/revocations (D028)
  15. veterancy_system()      — Award XP from kills, check level-up thresholds
  16. death_system()          — Remove destroyed entities, spawn husks, apply on-death warheads
  17. crate_system()          — Check crate pickups, apply random actions, spawn new crates
  18. transform_system()      — Process pending unit transformations (MCV ↔ ConYard, deploy/undeploy)
  19. trigger_system()        — Check mission/map triggers (Lua callbacks)
  20. notification_system()   — Queue audio/visual notifications (EVA, alerts), enforce cooldowns
  21. fog_system()            — Update visibility (staggered — not every tick, see 10-PERFORMANCE.md)

Order is fixed per game module and documented. Changing it changes gameplay and breaks replay compatibility.

A different game module (e.g., RA2) can insert additional systems (garrison, mind control, prism forwarding) at defined points. The engine runs whatever systems the active game module registers, in the order it specifies. The engine itself doesn’t know which game is running — it just executes the registered system pipeline deterministically.

FogProvider Trait (D041)

fog_system() delegates visibility computation to a FogProvider trait — like Pathfinder for pathfinding. Different game modules need different fog algorithms: radius-based (RA1), elevation line-of-sight (RA2/TS), or no fog (sandbox).

#![allow(unused)]
fn main() {
/// Game modules implement this to define how visibility is computed.
pub trait FogProvider: Send + Sync {
    /// Recompute visibility for a player.
    fn update_visibility(
        &mut self,
        player: PlayerId,
        sight_sources: &[(WorldPos, SimCoord)],  // (position, sight_range) pairs
        terrain: &TerrainData,
    );

    /// Is this position currently visible to this player?
    fn is_visible(&self, player: PlayerId, pos: WorldPos) -> bool;

    /// Has this player ever seen this position? (shroud vs fog distinction)
    fn is_explored(&self, player: PlayerId, pos: WorldPos) -> bool;

    /// All entity IDs visible to this player (for AI view filtering, render culling).
    fn visible_entities(&self, player: PlayerId) -> &[EntityId];
}
}

RA1 registers RadiusFogProvider (circle-based, fast, matches original RA). RA2/TS would register ElevationFogProvider (raycasts against terrain heightmap). A deferred fog-authoritative NetworkModel variant (not part of M1-M4; see multiplayer trust/productization milestones) reuses the same trait on the server side to determine which entities to send per client. See D041 in decisions/09d-gameplay.md for full rationale.

Entity Visibility Model

The FogProvider output determines how entities appear to each player. Following SC2’s proven model (see research/blizzard-github-analysis.md § 1.4), each entity observed by a player carries a visibility classification that controls which data fields are available:

#![allow(unused)]
fn main() {
/// Per-entity visibility state as seen by a specific player.
/// Determines which component fields the player can observe.
pub enum EntityVisibility {
    /// Currently visible — all public fields available (health, position, orders for own units).
    Visible,
    /// Previously visible, now in fog — "ghost" of last-known state.
    /// Position/type from when last seen; health, orders, and internal state are NOT available.
    Snapshot,
    /// Never seen or fully hidden — no data available to this player.
    Hidden,
}
}

Field filtering per visibility level:

Last-seen snapshot table: When a visible entity enters fog-of-war, the FogProvider stores a snapshot of its last-known position, type, owner, and build progress. The renderer displays this as a dimmed “ghost” unit. The snapshot is explicitly stale — the actual unit may have moved, morphed, or been destroyed. Snapshots are cleared when the position is re-explored and the unit is no longer there.

Double-Buffered Shared State (Tick-Consistent Reads)

Multiple systems per tick need to read shared, expensive-to-compute data structures — fog visibility, influence maps, global condition modifiers (D028). The FogProvider output is the clearest example: targeting_system(), ai_system(), and render all need to answer “is this cell visible?” within the same tick. If fog_system() updates visibility mid-tick, some systems see old fog, others see new — a determinism violation.

IC uses double buffering for any shared state that is written by one system and read by many systems within a tick:

#![allow(unused)]
fn main() {
/// Two copies of T — one for reading (current tick), one for writing (being rebuilt).
/// Swap at tick boundary. All reads within a tick see a consistent snapshot.
pub struct DoubleBuffered<T> {
    /// Current tick — all systems read from this. Immutable during the tick.
    read: T,
    /// Next tick — one system writes to this during the current tick.
    write: T,
}

impl<T> DoubleBuffered<T> {
    /// Called exactly once per tick, at the tick boundary, before any systems run.
    /// After swap, the freshly-computed write buffer becomes the new read buffer.
    pub fn swap(&mut self) {
        std::mem::swap(&mut self.read, &mut self.write);
    }

    /// All systems call this to read — guaranteed consistent for the entire tick.
    pub fn read(&self) -> &T { &self.read }

    /// Only the owning system (e.g., fog_system) calls this to prepare the next tick.
    pub fn write(&mut self) -> &mut T { &mut self.write }
}
}

Where double buffering applies:

Why not Bevy’s system ordering alone? Bevy’s scheduler can enforce that fog_system() runs before targeting_system(). But it cannot prevent a system scheduled between two readers from mutating shared state. Double buffering makes the guarantee structural: the read buffer is physically separate from the write buffer. No scheduling mistake can cause a reader to see partial writes.

Cost: One extra copy of each double-buffered data structure. For fog visibility (a bit array over map cells), this is ~32KB for a 512×512 map. For influence maps (a [i32; CELLS] array), it’s ~1MB for a 512×512 map. These are allocated once at game start and never reallocated — consistent with Layer 5’s zero-allocation principle.

Swap timing: DoubleBuffered::swap() is called in Simulation::apply_tick() before the system pipeline runs. This is a fixed point in the tick — step 0, before step 1 (order_validation_system()). The write buffer from the previous tick becomes the read buffer for the current tick. The swap is a pointer swap (std::mem::swap), not a copy — effectively free.

OrderValidator Trait (D041)

The engine enforces that ALL orders pass validation before apply_orders() executes them. This formalizes D012’s anti-cheat guarantee — game modules cannot accidentally skip validation:

#![allow(unused)]
fn main() {
/// Game modules implement this to define legal orders. The engine calls
/// validate() for every order, every tick — before the module's systems run.
pub trait OrderValidator: Send + Sync {
    fn validate(
        &self,
        player: PlayerId,
        order: &PlayerOrder,
        state: &SimReadView,
    ) -> OrderValidity;
}
}

RA1 registers StandardOrderValidator (ownership, affordability, prerequisites, placement, rate limits). See D041 in decisions/09d-gameplay.md for full design and GameModule trait integration.

Extended Gameplay Systems (RA1 Module)

Moved to architecture/gameplay-systems.md for RAG/context efficiency.

The 9 core components above cover the skeleton. A playable Red Alert requires ~50 components and ~20 systems power, construction, production, harvesting, combat, fog of war, shroud, crates, veterancy, carriers, mind control, iron curtain, chronosphere, and more.

Architecture Sub-Pages

Core Architecture Extended Gameplay Systems (RA1 Module)

The 9 core components in the main architecture document cover the skeleton. A playable Red Alert requires ~50 components and ~20 systems. This section designs every gameplay system identified in 11-OPENRA-FEATURES.md gap analysis, organized by functional domain.

Power System

Every building generates or consumes power. Power deficit disables defenses and slows production — core C&C economy.

#![allow(unused)]
fn main() {
/// Per-building power contribution.
pub struct Power {
    pub provides: i32,   // Power plants: positive
    pub consumes: i32,   // Defenses, production buildings: positive
}

/// Marker: this building goes offline during power outage.
pub struct AffectedByPowerOutage;

/// Player-level resource (not a component — stored in PlayerState).
pub struct PowerManager {
    pub total_capacity: i32,
    pub total_drain: i32,
    pub low_power: bool,  // drain > capacity
}
}

power_system() logic: Sum all Power components per player → update PowerManager. When low_power is true, buildings with AffectedByPowerOutage have their production rates halved and defenses fire at reduced rate (via condition system, D028). Power bar UI reads PowerManager from ic-ui.

YAML:

power_plant:
  power: { provides: 100 }
tesla_coil:
  power: { consumes: 75 }
  affected_by_power_outage: true

Full Damage Pipeline (D028)

The complete weapon → projectile → warhead chain:

Armament fires → Projectile entity spawned → projectile_system() advances it
  → hit detection (range, homing, ballistic arc)
  → Warhead(s) applied at impact point
    → target validity (TargetTypes, stances)
    → spread/falloff calculation (distance from impact)
    → Versus table lookup (ArmorType × WarheadType → damage multiplier)
    → DamageMultiplier modifiers (veterancy, terrain, conditions)
    → Health reduced

#![allow(unused)]
fn main() {
/// A fired projectile — exists as its own entity during flight.
pub struct Projectile {
    pub weapon_id: WeaponId,
    pub source: EntityId,
    pub owner: PlayerId,
    pub target: ProjectileTarget,
    pub speed: i32,            // fixed-point
    pub warheads: Vec<WarheadId>,
    pub inaccuracy: i32,       // scatter radius at target
    pub projectile_type: ProjectileType,
}

pub enum ProjectileType {
    Bullet,         // instant-hit (hitscan)
    Missile { tracking: i32, rof_jitter: i32 },  // homing
    Ballistic { gravity: i32 },                    // arcing (artillery)
    Beam { duration: u32 },                        // continuous ray
}

pub enum ProjectileTarget {
    Entity(EntityId),
    Ground(WorldPos),
}

/// Warhead definition — loaded from YAML, shared (not per-entity).
pub struct WarheadDef {
    pub spread: i32,           // area of effect radius
    pub versus: VersusTable,   // ArmorType → damage percentage
    pub damage: i32,           // base damage value
    pub falloff: Vec<i32>,     // damage multiplier at distance steps
    pub valid_targets: Vec<TargetType>,
    pub invalid_targets: Vec<TargetType>,
    pub effects: Vec<WarheadEffect>,  // screen shake, spawn fire, etc.
}

/// ArmorType × WarheadType → percentage (100 = full damage)
/// Loaded from YAML Versus table — identical format to OpenRA.
/// Flat array indexed by ArmorType discriminant for O(1) lookup in the combat
/// hot path — no per-hit HashMap overhead. ArmorType is a small enum (<16 variants)
/// so the array fits in a single cache line.
pub struct VersusTable {
    pub modifiers: [i32; ArmorType::COUNT],  // index = ArmorType as usize
}
}

projectile_system() logic: For each Projectile entity: advance position by speed, check if arrived at target. On arrival, iterate warheads, apply each to entities in spread radius using SpatialIndex::query_range(). For each target: check valid_targets, look up VersusTable, apply DamageMultiplier conditions, reduce Health. If Health.current <= 0, mark for death_system().

YAML (weapon + warhead, OpenRA-compatible):

weapons:
  105mm:
    range: 5120          # in world units (fixed-point)
    rate_of_fire: 80     # ticks between shots
    projectile:
      type: bullet
      speed: 682
    warheads:
      - type: spread_damage
        damage: 60
        spread: 426
        versus:
          none: 100
          light: 80
          medium: 60
          heavy: 40
          wood: 120
          concrete: 30
        falloff: [100, 50, 25, 0]

DamageResolver Trait (D041)

The damage pipeline above describes the RA1 resolution algorithm. The data (warheads, versus tables, modifiers) is YAML-configurable, but the resolution order — what happens between warhead impact and health reduction — varies between game modules. RA2 needs shield-first resolution; Generals-class games need sub-object targeting. The DamageResolver trait abstracts this step:

#![allow(unused)]
fn main() {
/// Game modules implement this to define damage resolution order.
/// Called by projectile_system() after hit detection and before health reduction.
pub trait DamageResolver: Send + Sync {
    fn resolve_damage(
        &self,
        warhead: &WarheadDef,
        target: &DamageTarget,
        modifiers: &StatModifiers,
        distance_from_impact: SimCoord,
    ) -> DamageResult;
}

pub struct DamageTarget {
    pub entity: EntityId,
    pub armor_type: ArmorType,
    pub current_health: i32,
    pub shield: Option<ShieldState>,
    pub conditions: Conditions,
}

pub struct DamageResult {
    pub health_damage: i32,
    pub shield_damage: i32,
    pub conditions_applied: Vec<(ConditionId, u32)>,
    pub overkill: i32,
}
}

RA1 registers StandardDamageResolver (Versus table → falloff → multiplier stack → health). RA2 would register ShieldFirstDamageResolver. See D041 in ../decisions/09d-gameplay.md for full rationale and alternative implementations.

Support Powers / Superweapons

#![allow(unused)]
fn main() {
/// Attached to the building that provides the power (e.g., Chronosphere, Iron Curtain device).
pub struct SupportPower {
    pub power_type: SupportPowerType,
    pub charge_time: u32,          // ticks to fully charge
    pub current_charge: u32,       // ticks accumulated
    pub ready: bool,
    pub one_shot: bool,            // nukes: consumed on use; Chronosphere: recharges
    pub targeting: TargetingMode,
}

pub enum TargetingMode {
    Point,                   // click a cell (nuke)
    Area { radius: i32 },   // area selection (Iron Curtain effect)
    Directional,             // select origin + target cell (Chronoshift)
}

pub enum SupportPowerType {
    /// Defined by YAML — these are RA1 defaults, but the enum is data-driven.
    Named(String),
}

/// Player-level tracking.
pub struct SupportPowerManager {
    pub powers: Vec<SupportPowerStatus>, // one per owned support building
}
}

support_power_system() logic: For each entity with SupportPower: increment current_charge each tick. When current_charge >= charge_time, set ready = true. UI shows charge bar. Activation comes via player order (sim validates ownership + readiness), then applies warheads/effects at target location.

Building Mechanics

#![allow(unused)]
fn main() {
/// Build radius — buildings can only be placed near existing structures.
pub struct BuildArea {
    pub range: i32,   // cells from building edge
}

/// Primary building marker — determines which building produces (e.g., primary war factory).
pub struct PrimaryBuilding;

/// Rally point — newly produced units move here.
pub struct RallyPoint {
    pub target: WorldPos,
}

/// Building exit points — where produced units spawn.
pub struct Exit {
    pub offsets: Vec<CellPos>,   // spawn positions relative to building origin
}

/// Building can be sold.
pub struct Sellable {
    pub refund_percent: i32,  // typically 50
    pub sell_time: u32,       // ticks for sell animation
}

/// Building can be repaired (by player spending credits).
pub struct Repairable {
    pub repair_rate: i32,     // HP per tick while repairing
    pub repair_cost_per_hp: i32,
}

/// Gate — wall segment that opens for friendly units.
pub struct Gate {
    pub open_delay: u32,
    pub close_delay: u32,
    pub state: GateState,
}

pub enum GateState { Open, Closed, Opening, Closing }

/// Wall-specific: enables line-build placement.
pub struct LineBuild;
}

Building placement validation (in apply_orders() → order validation):

1. Check footprint fits terrain (no water, no cliffs, no existing buildings)
2. Check within build radius of at least one friendly BuildArea provider
3. Check prerequisites met (from Buildable.prereqs)
4. Deduct cost → start build animation → spawn building entity

Production Queue

#![allow(unused)]
fn main() {
/// A production queue (each building type has its own queue).
pub struct ProductionQueue {
    pub queue_type: QueueType,
    pub items: Vec<ProductionItem>,
    pub parallel: bool,           // RA2: parallel production per factory
    pub paused: bool,
}

pub struct ProductionItem {
    pub actor_type: ActorId,
    pub remaining_cost: i32,
    pub remaining_time: u32,
    pub paid: i32,               // credits paid so far (for pause/resume)
    pub infinite: bool,          // repeat production (hold queue)
}
}

production_system() logic: For each ProductionQueue: if not paused and not empty, advance front item. Deduct credits incrementally (one tick’s worth per tick — production slows when credits run out). When remaining_time == 0, spawn unit at building’s Exit position, send to RallyPoint if set.

Production Model Diversity

The ProductionQueue above describes the classic C&C sidebar model, but production is one of the most varied mechanics across RTS games — even within the OpenRA mod ecosystem. Analysis of six major OpenRA mods (see research/openra-mod-architecture-analysis.md) reveals at least five distinct production models:

The engine must not hardcode any of these. The production_system() described above is the RA1 game module’s implementation. Other game modules register their own production system via GameModule::system_pipeline(). The ProductionQueue component is defined by the game module, not the engine core. A KKnD-style module might define a PerBuildingProductionQueue component with different constraints; a Dune II module might omit queue mechanics entirely and use a SingleItemProduction component.

This is a key validation of invariant #9 (engine core is game-agnostic): if a non-C&C total conversion on our engine needs a fundamentally different production model, the engine should not resist it.

Resource / Ore Model

#![allow(unused)]
fn main() {
/// Ore/gem cell data — stored per map cell (in a resource layer, not as entities).
pub struct ResourceCell {
    pub resource_type: ResourceType,
    pub amount: i32,     // depletes as harvested
    pub max_amount: i32,
    pub growth_rate: i32, // ore regrows; gems don't (YAML-configured)
}

/// Storage capacity — silos and refineries.
pub struct ResourceStorage {
    pub capacity: i32,
}
}

harvester_system() logic:

1. Harvester navigates to nearest ResourceCell with amount > 0
2. Harvester mines: transfers resource from cell to Harvester.capacity
3. When full (or cell depleted): navigate to nearest DockHost with DockType::Refinery
4. Dock, transfer resources → credits (via resource value table)
5. If no refinery, wait. If no ore, scout for new fields.

Player receives “silos needed” notification when total stored exceeds total ResourceStorage.capacity.

Transport / Cargo

#![allow(unused)]
fn main() {
pub struct Cargo {
    pub max_weight: u32,
    pub current_weight: u32,
    pub passengers: Vec<EntityId>,
    pub unload_delay: u32,
}

pub struct Passenger {
    pub weight: u32,
    pub custom_pip: Option<PipType>,  // minimap/selection pip color
}

/// For carryall-style air transport.
pub struct Carryall {
    pub carry_target: Option<EntityId>,
}

/// Eject passengers on death (not all transports — YAML-configured).
pub struct EjectOnDeath;

/// ParaDrop capability — drop passengers from air.
pub struct ParaDrop {
    pub drop_interval: u32,  // ticks between each passenger exiting
}
}

Load order: Player issues load order → movement_system() moves passenger to transport → when adjacent, remove passenger from world, add to Cargo.passengers. Unload order: Deploy order → eject passengers one by one at Exit positions, delay between each.

Capture / Ownership

#![allow(unused)]
fn main() {
pub struct Capturable {
    pub capture_types: Vec<CaptureType>,  // engineer, proximity
    pub capture_threshold: i32,           // required capture points
    pub current_progress: i32,
    pub capturing_entity: Option<EntityId>,
}

pub struct Captures {
    pub speed: i32,              // capture points per tick
    pub capture_type: CaptureType,
    pub consumed: bool,          // engineer is consumed on capture (RA1 behavior)
}

pub enum CaptureType { Infantry, Proximity }
}

capture_system() logic: For each entity with Capturable being captured: increment current_progress by capturer’s speed. When current_progress >= capture_threshold, transfer ownership to capturer’s player. If consumed, destroy capturer. Reset progress on interruption (capturer killed or moved away).

Stealth / Cloak

#![allow(unused)]
fn main() {
pub struct Cloak {
    pub cloak_delay: u32,         // ticks after last action before cloaking
    pub cloak_types: Vec<CloakType>,
    pub ticks_since_action: u32,
    pub is_cloaked: bool,
    pub reveal_on_fire: bool,
    pub reveal_on_move: bool,
}

pub struct DetectCloaked {
    pub range: i32,
    pub detect_types: Vec<CloakType>,
}

pub enum CloakType { Stealth, Underwater, Disguise, GapGenerator }
}

cloak_system() logic: For each Cloak entity: if reveal_on_fire and fired this tick, reset ticks_since_action. If reveal_on_move and moved this tick, reset. Otherwise increment ticks_since_action. When above cloak_delay, set is_cloaked = true. Rendering: cloaked and no enemy DetectCloaked in range → invisible. Cloaked but detected → shimmer effect. Fog system integration: cloaked entities hidden from enemy even in explored area unless detector present.

Infantry Mechanics

#![allow(unused)]
fn main() {
/// Infantry sub-cell positioning — up to 5 infantry per cell.
pub struct InfantryBody {
    pub sub_cell: SubCell,  // Center, TopLeft, TopRight, BottomLeft, BottomRight
}

pub enum SubCell { Center, TopLeft, TopRight, BottomLeft, BottomRight }

/// Panic flee behavior (e.g., civilians, dogs).
pub struct ScaredyCat {
    pub flee_range: i32,
    pub panic_ticks: u32,
}

/// Take cover / prone — reduces damage, reduces speed.
pub struct TakeCover {
    pub damage_modifier: i32,   // e.g., 50 (half damage)
    pub speed_modifier: i32,    // e.g., 50 (half speed)
    pub prone_delay: u32,       // ticks to transition to prone
}
}

movement_system() integration for infantry: When infantry moves into a cell, assigns SubCell based on available slots. Up to 5 infantry share one cell in different visual positions. When attacked, infantry with TakeCover auto-goes prone (grants condition “prone” → DamageMultiplier of 50%).

Death Mechanics

#![allow(unused)]
fn main() {
/// Spawn an actor when this entity dies (husks, ejected pilots).
pub struct SpawnOnDeath {
    pub actor_type: ActorId,
    pub probability: i32,   // 0-100, default 100
}

/// Explode on death — apply warheads at position.
pub struct ExplodeOnDeath {
    pub warheads: Vec<WarheadId>,
}

/// Timed self-destruct (demo truck, C4 charge).
pub struct SelfDestruct {
    pub timer: u32,        // ticks remaining
    pub warheads: Vec<WarheadId>,
}

/// Damage visual states.
pub struct DamageStates {
    pub thresholds: Vec<DamageThreshold>,
}

pub struct DamageThreshold {
    pub hp_percent: i32,   // below this → enter this state
    pub state: DamageState,
}

pub enum DamageState { Undamaged, Light, Medium, Heavy, Critical }

/// Victory condition marker — this entity must be destroyed to win.
pub struct MustBeDestroyed;
}

death_system() logic: For entities with Health.current <= 0: check SpawnOnDeath → spawn husk/pilot. Check ExplodeOnDeath → apply warheads at position. Remove entity from world and spatial index. For SelfDestruct: decrement timer each tick in a pre-death pass; when 0, kill the entity (triggers normal death path).

Transform / Deploy

#![allow(unused)]
fn main() {
/// Actor can transform into another type (MCV ↔ ConYard, siege deploy/undeploy).
pub struct Transforms {
    pub into: ActorId,
    pub delay: u32,              // ticks for transformation
    pub facing: Option<i32>,     // required facing to transform
    pub condition: Option<ConditionId>,  // condition granted during transform
}
}

Processing: Player issues deploy order → transform_system() starts countdown. During delay, entity is immobile (grants condition “deploying”). After delay, replace entity with into actor type, preserving health percentage, owner, and veterancy.

Docking System

#![allow(unused)]
fn main() {
/// Building or unit that accepts docking (refinery, helipad, repair pad).
pub struct DockHost {
    pub dock_type: DockType,
    pub dock_position: CellPos,  // where the client unit sits
    pub queue: Vec<EntityId>,    // waiting to dock
    pub occupied: bool,
}

/// Unit that needs to dock (harvester, aircraft, damaged vehicle for repair pad).
pub struct DockClient {
    pub dock_type: DockType,
}

pub enum DockType { Refinery, Helipad, RepairPad }
}

docking_system() logic: For each DockHost: if not occupied and queue non-empty, pull front of queue, guide to dock_position. When docked: execute dock-type-specific logic (refinery → transfer resources; helipad → reload ammo; repair pad → heal). When done, release and advance queue.

Veterancy / Experience

#![allow(unused)]
fn main() {
/// This unit gains XP from kills.
pub struct GainsExperience {
    pub current_xp: i32,
    pub level: VeterancyLevel,
    pub thresholds: Vec<i32>,      // XP required for each level transition
    pub level_conditions: Vec<ConditionId>,  // conditions granted at each level
}

/// This unit awards XP when killed (based on its cost/value).
pub struct GivesExperience {
    pub value: i32,   // XP awarded to killer
}

pub enum VeterancyLevel { Rookie, Veteran, Elite, Heroic }
}

veterancy_system() logic: When death_system() removes an entity with GivesExperience, the killer (if it has GainsExperience) receives value XP. Check thresholds: if XP crosses a boundary, advance level and grant the corresponding condition. Conditions trigger multipliers: veteran = +25% firepower/+25% armor; elite = +50%/+50% + self-heal; heroic = +75%/+75% + faster fire rate (all values from YAML, not hardcoded).

Campaign carry-over (D021): GainsExperience.current_xp and level are part of the roster snapshot saved between campaign missions.

Guard Command

#![allow(unused)]
fn main() {
pub struct Guard {
    pub target: EntityId,
    pub leash_range: i32,   // max distance from target before returning
}

pub struct Guardable;  // marker: can be guarded
}

Processing in apply_orders(): Guard order assigns Guard component. combat_system() integration: if a guarding unit’s target is attacked and attacker is within leash range, engage attacker. If target moves beyond leash range, follow.

Crush Mechanics

#![allow(unused)]
fn main() {
pub struct Crushable {
    pub crush_class: CrushClass,
}

pub enum CrushClass { Infantry, Wall, Hedgehog }

/// Vehicles that auto-crush when moving over crushable entities.
pub struct Crusher {
    pub crush_classes: Vec<CrushClass>,
}
}

crush_system() logic: After movement_system(), for each entity with Crusher that moved this tick: query SpatialIndex at new position for entities with matching Crushable.crush_class. Apply instant kill to crushed entities.

Crate System

#![allow(unused)]
fn main() {
pub struct Crate {
    pub action_pool: Vec<CrateAction>,  // weighted random selection
}

pub enum CrateAction {
    Cash { amount: i32 },
    Unit { actor_type: ActorId },
    Heal { percent: i32 },
    LevelUp,
    MapReveal,
    Explode { warhead: WarheadId },
    Cloak { duration: u32 },
    Speed { multiplier: i32, duration: u32 },
}

/// World-level system resource.
pub struct CrateSpawner {
    pub max_crates: u32,
    pub spawn_interval: u32,   // ticks between spawn attempts
    pub spawn_area: SpawnArea,
}
}

crate_system() logic: Periodically spawn crates (up to max_crates). When a unit moves onto a crate: pick random CrateAction, apply effect to collecting unit/player. Remove crate entity.

Mine System

#![allow(unused)]
fn main() {
pub struct Mine {
    pub trigger_types: Vec<TargetType>,
    pub warhead: WarheadId,
    pub visible_to_owner: bool,
}

pub struct Minelayer {
    pub mine_type: ActorId,
    pub lay_delay: u32,
}
}

mine_system() logic: After movement_system(), for each Mine: query spatial index for entities at mine position matching trigger_types. On contact: apply warhead, destroy mine. Mines are invisible to enemy unless detected by mine-sweeper unit (uses DetectCloaked with CloakType::Stealth).

Notification System

#![allow(unused)]
fn main() {
pub struct NotificationEvent {
    pub event_type: NotificationType,
    pub position: Option<WorldPos>,  // for spatial notifications
    pub player: PlayerId,
}

pub enum NotificationType {
    UnitLost,
    BaseUnderAttack,
    HarvesterUnderAttack,
    BuildingCaptured,
    LowPower,
    SilosNeeded,
    InsufficientFunds,
    BuildingComplete,
    UnitReady,
    NuclearLaunchDetected,
    EnemySpotted,
    ReinforcementsArrived,
}

/// Per-notification-type cooldown (avoid spam).
/// Flat array indexed by NotificationType discriminant — small fixed enum,
/// avoids HashMap overhead on a per-event check.
pub struct NotificationCooldowns {
    pub cooldowns: [u32; NotificationType::COUNT],  // ticks remaining, index = variant as usize
    pub default_cooldown: u32,                       // typically 150 ticks (~10 sec)
}
}

notification_system() logic: Collects events from other systems (combat → “base under attack”, production → “building complete”, power → “low power”). Checks cooldown for each type. If not on cooldown, queues notification for ic-audio (EVA voice line) and ic-ui (text overlay). Audio mapping is YAML-driven:

notifications:
  base_under_attack: { audio: "BATL1.AUD", priority: high, cooldown: 300 }
  building_complete: { audio: "CONSTRU2.AUD", priority: normal, cooldown: 0 }
  low_power: { audio: "LOPOWER1.AUD", priority: high, cooldown: 600 }

Cursor System

#![allow(unused)]
fn main() {
/// Determines which cursor shows when hovering over a target.
pub struct CursorProvider {
    pub cursor_map: HashMap<CursorContext, CursorDef>,
}

pub enum CursorContext {
    Default,
    Move,
    Attack,
    AttackForce,     // force-fire on ground
    Capture,
    Enter,           // enter transport/building
    Deploy,
    Sell,
    Repair,
    Guard,
    SupportPower(SupportPowerType),
    Chronoshift,
    Nuke,
    Harvest,
    Impassable,
}

pub struct CursorDef {
    pub sprite: SpriteId,
    pub hotspot: (i32, i32),
    pub sequence: Option<AnimSequence>,  // animated cursors
}
}

Logic: Each frame (render-side, not sim), determine cursor context from: selected units, hovered entity/terrain, active command mode (sell, repair, support power), force modifiers (Ctrl = force-fire, Alt = force-move). Look up CursorDef from CursorProvider. Display.

Hotkey System

#![allow(unused)]
fn main() {
pub struct HotkeyConfig {
    pub bindings: HashMap<ActionId, Vec<KeyCombo>>,
    pub profiles: HashMap<String, HotkeyProfile>,
}

pub struct KeyCombo {
    pub key: KeyCode,
    pub modifiers: Modifiers,  // Ctrl, Shift, Alt
}
}

Built-in profiles:

• classic — original RA1 keybindings
• openra — OpenRA defaults
• modern — WASD camera, common RTS conventions

Fully rebindable in settings UI. Categories: unit commands, production, control groups, camera, chat, debug. Hotkeys produce PlayerOrders through InputSource — the sim never sees key codes.

Camera System

The camera is a purely render-side concern — the sim has no camera concept (Invariant #1). Camera state lives as a Bevy Resource in ic-render, read by the rendering pipeline and ic-ui (minimap, spatial audio listener position). The ScreenToWorld trait (see § “Portability Design Rules”) converts screen coordinates to world positions; the camera system controls what region of the world is visible.

Core Types

#![allow(unused)]
fn main() {
/// Central camera state — a Bevy Resource in ic-render.
/// NOT part of the sim. Save/restore for save games is serialized separately
/// (alongside other client-side state like UI layout and audio volume).
#[derive(Resource)]
pub struct GameCamera {
    /// World position the camera is centered on (render-side f32, not sim fixed-point).
    pub position: Vec2,
    /// Current zoom level. 1.0 = default view. <1.0 = zoomed out, >1.0 = zoomed in.
    pub zoom: f32,
    /// Zoom limits — enforced every frame. Ranked/tournament modes clamp these further.
    pub zoom_min: f32,  // default: 0.5 (see twice as much map)
    pub zoom_max: f32,  // default: 4.0 (pixel-level inspection)
    /// Map bounds in world coordinates — camera cannot scroll past these.
    pub bounds: Rect,
    /// Smooth interpolation factor for zoom (0.0–1.0 per frame, lerp toward target).
    pub zoom_smoothing: f32,  // default: 0.15
    /// Smooth interpolation factor for pan.
    pub pan_smoothing: f32,   // default: 0.2
    /// Internal: zoom target for smooth interpolation.
    pub zoom_target: f32,
    /// Internal: position target for smooth pan (e.g., centering on selection).
    pub position_target: Vec2,
    /// Edge scroll speed in world-units per second (scaled by current zoom).
    pub edge_scroll_speed: f32,
    /// Keyboard pan speed in world-units per second (scaled by current zoom).
    pub keyboard_pan_speed: f32,
    /// Follow mode: lock camera to a unit or player's view.
    pub follow_target: Option<FollowTarget>,
    /// Screen shake state (driven by explosions, nukes, superweapons).
    pub shake: ScreenShake,
}

pub enum FollowTarget {
    Unit(UnitTag),               // follow a specific unit (observer, cinematic)
    Player(PlayerId),            // lock to a player's viewport (observer mode)
}

pub struct ScreenShake {
    pub amplitude: f32,          // current intensity (decays over time)
    pub decay_rate: f32,         // amplitude reduction per second
    pub frequency: f32,          // oscillation speed
    pub offset: Vec2,            // current frame's shake offset (applied to final transform)
}
}

Zoom Behavior

Zoom modifies the OrthographicProjection.scale on the Bevy camera entity. A zoom of 1.0 maps to the default viewport size for the active render mode (D048). Zooming out (zoom < 1.0) shows more of the map; zooming in (zoom > 1.0) magnifies the view.

Input methods:

Zoom-toward-cursor is the expected UX for isometric games (SC2, AoE2, OpenRA all do this). When the player scrolls the mouse wheel, the world point under the cursor stays fixed on screen — the camera position shifts to compensate for the scale change. This requires adjusting position alongside zoom:

#![allow(unused)]
fn main() {
fn zoom_toward_cursor(camera: &mut GameCamera, cursor_world: Vec2, scroll_delta: f32) {
    let old_zoom = camera.zoom_target;
    camera.zoom_target = (old_zoom + scroll_delta * ZOOM_STEP)
        .clamp(camera.zoom_min, camera.zoom_max);
    // Shift position so the cursor's world point stays at the same screen location.
    let zoom_ratio = camera.zoom_target / old_zoom;
    camera.position_target = cursor_world + (camera.position_target - cursor_world) * zoom_ratio;
}
}

Smooth interpolation: The actual zoom and position values lerp toward their targets each frame:

#![allow(unused)]
fn main() {
fn camera_interpolation(camera: &mut GameCamera, dt: f32) {
    let t_zoom = 1.0 - (1.0 - camera.zoom_smoothing).powf(dt * 60.0);
    camera.zoom = camera.zoom.lerp(camera.zoom_target, t_zoom);
    let t_pan = 1.0 - (1.0 - camera.pan_smoothing).powf(dt * 60.0);
    camera.position = camera.position.lerp(camera.position_target, t_pan);
}
}

This frame-rate-independent smoothing (exponential lerp) feels identical at 30 fps and 240 fps. The powf() call is once per frame, not per entity — negligible cost.

Discrete vs. continuous: Keyboard zoom (+/-) uses discrete steps (e.g., 0.25 increments). Mouse scroll uses finer steps (0.1). Both feed zoom_target and smooth toward it. There is NO “snap to integer zoom” constraint — smooth zoom is the default behavior. Classic render mode (D048) with integer scaling uses the same smooth zoom for camera movement but snaps the OrthographicProjection.scale to the nearest integer multiple when rendering, preventing sub-pixel shimmer on pixel art.

Zoom Interaction with Render Modes (D048)

Different render modes have different zoom characteristics:

When a render mode switch occurs (F1 / D048), the camera system adjusts:

• zoom_min / zoom_max to the new mode’s range
• zoom_target is clamped to the new range (if current zoom exceeds new limits)
• Camera position is preserved — only the zoom behavior changes

For 3D render modes, zoom maps to camera distance from the ground plane (dolly) rather than orthographic scale. The ScreenToWorld trait abstracts this — the camera system sets a zoom value, and the active ScreenToWorld implementation interprets it appropriately (orthographic scale for 2D, distance for 3D).

Pan (Scrolling)

Four input methods, all producing the same result — a position_target update:

Speed scales with zoom: When zoomed out, pan speed increases proportionally so map traversal time feels consistent. When zoomed in, pan speed decreases for precision. The scaling is linear: effective_speed = base_speed / zoom.

Bounds clamping: Every frame, position_target is clamped so the viewport stays within bounds (map rectangle plus a configurable padding). The player cannot scroll to see void beyond the map edge. Bounds are set when the map loads and do not change during gameplay.

Screen Shake

Triggered by game events (explosions, superweapons, building destruction) via Bevy events:

#![allow(unused)]
fn main() {
pub struct CameraShakeEvent {
    pub epicenter: WorldPos,   // world position of the explosion
    pub intensity: f32,        // 0.0–1.0 (nuke = 1.0, tank shell = 0.05)
    pub duration_secs: f32,    // how long the shake lasts
}
}

The shake system calculates amplitude from intensity, attenuated by distance from the camera. Multiple concurrent shakes are additive (capped at a maximum amplitude). The shake.offset is applied to the final camera transform each frame — it never modifies position or position_target, so the shake doesn’t drift the view.

Players can disable screen shake entirely via settings (/camera_shake off — D058) or reduce intensity with a slider. Accessibility concern: excessive screen shake can cause motion sickness.

Camera in Replays and Save Games

• Save games: GameCamera state (position, zoom, follow target) is serialized alongside other client-side state. On load, the camera restores to where the player was looking.
• Replays: CameraPositionSample events (see 05-FORMATS.md) record each player’s viewport center and zoom level at 2 Hz. Replay viewers can follow any player’s camera or use free camera. The replay camera is independent of the recorded camera data — the viewer controls their own viewport.
• Observer mode: Observers have independent camera control with no zoom restrictions (they can zoom out further than players for overview). The follow_player option (see ObserverState) syncs the observer’s camera to a player’s recorded CameraPositionSample stream.

Camera Configuration (YAML)

Per-game-module camera defaults:

camera:
  zoom:
    default: 1.0
    min: 0.5
    max: 4.0
    step_scroll: 0.1       # mouse wheel increment
    step_keyboard: 0.25    # +/- key increment
    smoothing: 0.15        # lerp factor (0 = instant, 1 = no movement)
    # Ranked override — competitive committee (D037) sets these per season
    ranked_min: 0.75
    ranked_max: 2.0
  pan:
    edge_scroll_speed: 1200.0   # world-units/sec at zoom 1.0
    keyboard_speed: 1000.0
    smoothing: 0.2
    edge_scroll_zone: 8        # pixels from screen edge to trigger
  shake:
    max_amplitude: 12.0         # max pixel displacement
    decay_rate: 8.0             # amplitude reduction per second
    enabled: true               # default; player can override in settings
  bounds_padding: 64            # extra world-units beyond map edges

This makes camera behavior fully data-driven (Principle 4 from 13-PHILOSOPHY.md). A Tiberian Sun module can set different zoom ranges (its taller buildings need more zoom-out headroom). A total conversion can disable edge scrolling entirely if it uses a different camera paradigm.

Game Speed

#![allow(unused)]
fn main() {
/// Lobby-configurable game speed.
pub struct GameSpeed {
    pub preset: SpeedPreset,
    pub tick_interval_ms: u32,   // sim tick period
}

pub enum SpeedPreset {
    Slowest,   // 80ms per tick
    Slower,    // 67ms per tick (default)
    Normal,    // 50ms per tick
    Faster,    // 35ms per tick
    Fastest,   // 20ms per tick
}
}

Speed affects only the interval between sim ticks — system behavior is tick-count-based, so all game logic works identically at any speed. Single-player can change speed mid-game; multiplayer sets it in lobby (synced).

Faction System

#![allow(unused)]
fn main() {
/// Faction identity — loaded from YAML.
pub struct Faction {
    pub internal_name: String,   // "allies", "soviet"
    pub display_name: String,    // "Allied Forces"
    pub side: String,            // "allies", "soviet" (for grouping subfactions)
    pub color: PlayerColor,
    pub tech_tree: TechTreeId,
    pub starting_units: Vec<StartingUnit>,
}
}

Factions determine: available tech tree (which units/buildings can be built), default player color, starting unit composition in skirmish, lobby selection, and Buildable.prereqs resolution. RA2 subfactions (e.g., Korea, Libya) share a side but differ in tech_tree (one unique unit each).

Auto-Target / Turret

#![allow(unused)]
fn main() {
/// Unit auto-acquires targets within range.
pub struct AutoTarget {
    pub scan_range: i32,
    pub stance: Stance,
    pub prefer_priority: bool,   // prefer high-priority targets
}

pub enum Stance {
    HoldFire,      // never auto-attack
    ReturnFire,    // attack only if attacked
    Defend,        // attack enemies in range
    AttackAnything, // attack anything visible
}

/// Turreted weapon — rotates independently of body.
pub struct Turreted {
    pub turn_speed: i32,
    pub offset: WorldPos,      // turret mount point relative to body
    pub current_facing: i32,   // turret facing (0-255)
}

/// Weapon requires ammo — must reload at dock (helipad).
pub struct AmmoPool {
    pub max_ammo: u32,
    pub current_ammo: u32,
    pub reload_delay: u32,    // ticks per ammo at dock
}
}

combat_system() integration: For units with AutoTarget and no current attack order: scan SpatialIndex within scan_range. Filter by Stance rules. Pick highest-priority valid target. For Turreted units: rotate turret toward target at turn_speed per tick before firing. For AmmoPool units: decrement ammo on fire; when depleted, return to nearest DockHost with DockType::Helipad for reload.

Selection Details

#![allow(unused)]
fn main() {
pub struct SelectionPriority {
    pub priority: i32,         // higher = selected preferentially
    pub click_priority: i32,   // higher = wins click-through
}
}

Selection features:

• Priority: When box-selecting 200 units, combat units are selected over harvesters (higher priority)
• Double-click: Select all units of the same type on screen
• Tab cycling: Cycle through unit types within a selection group
• Control groups: 0-9 control groups, Ctrl+# to assign, # to select, double-# to center camera
• Isometric selection box: Diamond-shaped box selection for proper isometric hit-testing

Observer / Spectator UI

Observer mode (separate from player mode) displays overlays not available to players:

#![allow(unused)]
fn main() {
pub struct ObserverState {
    pub show_army: bool,       // unit composition per player
    pub show_production: bool, // what each player is building
    pub show_economy: bool,    // income rate, credits per player
    pub show_powers: bool,     // superweapon charge timers
    pub show_score: bool,      // strategic score tracker
    pub follow_player: Option<PlayerId>,  // lock camera to player's view (writes GameCamera.follow_target)
}
}

Army overlay: Bar chart of unit counts per player, grouped by type. Production overlay: List of active queues per player. Economy overlay: Income rate graph. These are render-only — no sim interaction. Observer UI is an ic-ui concern.

Game Score / Performance Metrics

The sim tracks a comprehensive GameScore per player, updated every tick. This powers the observer economy overlay, post-game stats screen, and the replay analysis event stream (see 05-FORMATS.md § “Analysis Event Stream”). Design informed by SC2’s ScoreDetails protobuf (see research/blizzard-github-analysis.md § Part 2).

#![allow(unused)]
fn main() {
#[derive(Clone, Serialize, Deserialize)]
pub struct GameScore {
    // Economy
    pub total_collected: ResourceSet,      // lifetime resources harvested
    pub total_spent: ResourceSet,          // lifetime resources committed
    pub collection_rate: ResourceSet,      // current income per minute (fixed-point)
    pub idle_harvester_ticks: u64,         // cumulative ticks harvesters spent idle

    // Production
    pub units_produced: u32,
    pub structures_built: u32,
    pub idle_production_ticks: u64,        // cumulative ticks factories spent idle

    // Combat
    pub units_killed: u32,
    pub units_lost: u32,
    pub structures_destroyed: u32,
    pub structures_lost: u32,
    pub killed_value: ResourceSet,         // total value of enemy assets destroyed
    pub lost_value: ResourceSet,           // total value of own assets lost
    pub damage_dealt: i64,                 // fixed-point cumulative
    pub damage_received: i64,

    // Activity
    pub actions_per_minute: u32,           // APM (all orders)
    pub effective_actions_per_minute: u32, // EPM (non-redundant orders only)
}
}

APM vs EPM: Following SC2’s distinction — APM counts every order, EPM filters duplicate/redundant commands (e.g., repeatedly right-clicking the same destination). EPM is a better measure of meaningful player activity.

Sim-side only: GameScore lives in ic-sim (it’s deterministic state, not rendering). Observer overlays in ic-ui read it through the standard Simulation query interface.

Debug / Developer Tools

See also ../decisions/09g/D058-command-console.md for the unified chat/command console, cvar system, and Brigadier-style command tree that provides the text-based interface to these developer tools.

Developer mode (toggled in settings, not available in ranked):

#![allow(unused)]
fn main() {
pub struct DeveloperMode {
    pub instant_build: bool,
    pub free_units: bool,
    pub reveal_map: bool,
    pub unlimited_power: bool,
    pub invincible: bool,
    pub give_cash_amount: i32,
}
}

Debug overlays (via bevy_egui):

• Combat: weapon ranges as circles, target lines, damage numbers floating
• Pathfinding: flowfield visualization, path cost heat map, blocker highlight
• Performance: per-system tick time bar chart, entity count, memory usage
• Network: RTT graph, order latency, jitter, desync hash comparison
• Asset browser: preview sprites, sounds, palettes inline

Developer cheats issue special orders validated only when DeveloperMode is active. In multiplayer, all players must agree to enable dev mode (prevents cheating).

Security (V44): The consensus mechanism for multiplayer dev mode must be specified: dev mode is sim state (not client-side), toggled exclusively via PlayerOrder::SetDevMode with unanimous lobby consent before game start. Dev mode orders use a distinct PlayerOrder::DevCommand variant rejected by the sim when dev mode is inactive. Disabled for ranked matchmaking. See 06-SECURITY.md § Vulnerability 44.

Debug Drawing API

A programmatic drawing API for rendering debug geometry. Inspired by SC2’s DebugDraw interface (see research/blizzard-github-analysis.md § Part 7) — text, lines, boxes, and spheres rendered as overlays:

#![allow(unused)]
fn main() {
pub trait DebugDraw {
    fn draw_text(&mut self, pos: WorldPos, text: &str, color: Color);
    fn draw_line(&mut self, start: WorldPos, end: WorldPos, color: Color);
    fn draw_circle(&mut self, center: WorldPos, radius: i32, color: Color);
    fn draw_rect(&mut self, min: WorldPos, max: WorldPos, color: Color);
}
}

Used by AI visualization, pathfinding debug, weapon range display, and Lua/WASM debug scripts. All debug geometry is cleared each frame — callers re-submit every tick. Lives in ic-render (render concern, not sim).

Debug Unit Manipulation

Developer mode supports direct entity manipulation for testing:

• Spawn unit: Create any unit type at a position, owned by any player
• Kill unit: Instantly destroy selected entities
• Set resources: Override player credit balance
• Modify health: Set HP to any value

These operations are implemented as special PlayerOrder variants validated only when DeveloperMode is active. They flow through the normal order pipeline — deterministic across all clients.

Fault Injection (Testing Only)

For automated stability testing — not exposed in release builds:

• Hang simulation: Simulate tick timeout (verifies watchdog recovery)
• Crash process: Controlled exit (verifies crash reporting pipeline)
• Desync injection: Flip a bit in sim state (verifies desync detection and diagnosis)

These follow SC2’s DebugTestProcess pattern for CI/CD reliability testing.

Localization Framework

#![allow(unused)]
fn main() {
pub struct Localization {
    pub current_locale: String,         // "en", "de", "zh-CN"
    pub bundles: HashMap<String, FluentBundle>,  // locale → string bundle
}
}

Uses Project Fluent (same as OpenRA) for parameterized, pluralization-aware message formatting:

# en.ftl
unit-lost = Unit lost
base-under-attack = Our base is under attack!
building-complete = { $building } construction complete.
units-selected = { $count ->
    [one] {$count} unit selected
   *[other] {$count} units selected
}

Mods provide their own .ftl files. Engine strings are localizable from Phase 3. Community translations publishable to Workshop.

Encyclopedia

In-game unit/building/weapon reference browser:

#![allow(unused)]
fn main() {
pub struct EncyclopediaEntry {
    pub actor_type: ActorId,
    pub display_name: String,
    pub description: String,
    pub stats: HashMap<String, String>,  // "Speed: 8", "Armor: Medium"
    pub preview_sprite: SpriteId,
    pub category: EncyclopediaCategory,
}

pub enum EncyclopediaCategory { Infantry, Vehicle, Aircraft, Naval, Structure, Defense, Support }
}

Auto-generated from YAML rule definitions + optional encyclopedia: block in YAML. Accessible from main menu and in-game sidebar. Mod-defined units automatically appear in the encyclopedia.

Palette Effects (Runtime)

Beyond static .pal file loading (ra-formats), runtime palette manipulation for classic RA visual style:

#![allow(unused)]
fn main() {
pub enum PaletteEffect {
    PlayerColorRemap { remap_range: (u8, u8), target_color: PlayerColor },
    Rotation { start_index: u8, end_index: u8, speed: u32 },  // water animation
    CloakShimmer { entity: EntityId },
    ScreenFlash { color: PaletteColor, duration: u32 },       // nuke, chronoshift
    DamageTint { entity: EntityId, state: DamageState },
}
}

Modern implementation: These are shader effects in Bevy’s render pipeline, not literal palette index swaps. But the modder-facing YAML configuration matches the original palette effect names for familiarity. Shader implementations achieve the same visual result with modern GPU techniques (color lookup textures, screen-space post-processing).

Demolition / C4

#![allow(unused)]
fn main() {
pub struct Demolition {
    pub delay: u32,               // ticks to detonation
    pub warhead: WarheadId,
    pub required_target: TargetType,  // buildings only
}
}

Engineer-type unit with Demolition places C4 on a building. After delay ticks, warhead detonates. Target building takes massive damage (usually fatal). Engineer is consumed.

Plug System

#![allow(unused)]
fn main() {
pub struct Pluggable {
    pub plug_type: PlugType,
    pub max_plugs: u32,
    pub current_plugs: u32,
    pub effect_per_plug: ConditionId,
}

pub struct Plug {
    pub plug_type: PlugType,
}
}

Primarily RA2 (bio-reactor accepting infantry for extra power). Included for mod compatibility. When a Plug entity enters a Pluggable building, increment current_plugs, grant condition per plug (e.g., “+50 power per infantry in reactor”).

Game Loop

Game Loop

#![allow(unused)]
fn main() {
pub struct GameLoop<N: NetworkModel, I: InputSource> {
    sim: Simulation,
    renderer: Renderer,
    network: N,
    input: I,
    local_player: PlayerId,
    order_buf: Vec<TimestampedOrder>,  // reused across frames — zero allocation on hot path
}

impl<N: NetworkModel, I: InputSource> GameLoop<N, I> {
    fn frame(&mut self) {
        // 1. Gather local input with sub-tick timestamps
        self.input.drain_orders(&mut self.order_buf);
        for order in self.order_buf.drain(..) {
            self.network.submit_order(order);
        }

        // 2. Advance sim as far as confirmed orders allow
        while let Some(tick_orders) = self.network.poll_tick() {
            self.sim.apply_tick(&tick_orders);
            self.network.report_sync_hash(
                self.sim.tick(),
                self.sim.state_hash(),
            );
        }

        // 3. Render always runs, interpolates between sim states
        self.renderer.draw(&self.sim, self.interpolation_factor());
    }
}
}

Key property: GameLoop is generic over N: NetworkModel and I: InputSource. It has zero knowledge of whether it’s running single-player or multiplayer, or whether input comes from a mouse, touchscreen, or gamepad. This is the central architectural guarantee.

Game Lifecycle State Machine

The game application transitions through a fixed set of states. Design informed by SC2’s protocol state machine (see research/blizzard-github-analysis.md § Part 1), adapted for IC’s architecture:

┌──────────┐     ┌───────────┐     ┌─────────┐     ┌───────────┐
│ Launched │────▸│ InMenus   │────▸│ Loading │────▸│ InGame    │
└──────────┘     └───────────┘     └─────────┘     └───────────┘
                   ▲     │                            │       │
                   │     │                            │       │
                   │     ▼                            ▼       │
                   │   ┌───────────┐          ┌───────────┐   │
                   │   │ InReplay  │◂─────────│ GameEnded │   │
                   │   └───────────┘          └───────────┘   │
                   │         │                    │           │
                   └─────────┴────────────────────┘           │
                                                              ▼
                                                        ┌──────────┐
                                                        │ Shutdown │
                                                        └──────────┘

• Launched → InMenus: Engine initialization, asset loading, mod registration, and (when required) entry into the first-run setup wizard / setup assistant flow (D069). This remains menu/UI-only — no sim world exists yet.
• InMenus → Loading: Player starts a game or joins a lobby; map and rules are loaded
• Loading → InGame: All assets loaded, NetworkModel connected, sim initialized. See 03-NETCODE.md § “Match Lifecycle” for the ready-check and countdown protocol that governs this transition in multiplayer.
• InGame → GameEnded: Victory/defeat condition met, player surrenders (PlayerOrder::Surrender), vote-driven resolution (kick, remake, draw via the In-Match Vote Framework), or match void. See 03-NETCODE.md § “Match Lifecycle” for the surrender mechanic, team vote thresholds, and the generic callvote system.
• GameEnded → InMenus: Return to main menu (post-game stats shown during transition). See 03-NETCODE.md § “Post-Game Flow” for the 30-second post-game lobby with stats, rating display, and re-queue.
• GameEnded → InReplay: Watch the just-finished game (replay file already recorded)
• InMenus → InReplay: Load a saved replay file
• InReplay → InMenus: Exit replay viewer
• InGame → Shutdown: Application exit (snapshot saved for resume on platforms that require it)

State transitions are events in Bevy’s event system — plugins react to transitions without polling. The sim exists only during InGame and InReplay; all other states are menu/UI-only.

D069 integration: The installation/setup wizard is modeled as an InMenus subflow (UI-only) rather than a separate app state that changes sim/network invariants. Platform/store installers may precede launch, but IC-controlled setup runs after Launched → InMenus using platform capability metadata (see PlatformInstallerCapabilities in platform-portability.md).

State Recording & Replay Infrastructure

State Recording & Replay Infrastructure

The sim’s snapshottable design (D010) enables a StateRecorder/Replayer pattern for asynchronous background recording — inspired by Valve’s Source Engine StateRecorder/StateReplayer pattern (see research/valve-github-analysis.md § 2.2). The game loop records orders and periodic state snapshots to a background writer; the replay system replays them through the same Simulation::apply_tick() path.

StateRecorder (Recording Side)

#![allow(unused)]
fn main() {
/// Asynchronous background recording of game state.
/// Records orders every tick and full/delta snapshots periodically.
/// Runs on a background thread — zero impact on game loop latency.
///
/// Lives in ic-game (I/O concern, not sim concern — Invariant #1).
pub struct StateRecorder {
    /// Background thread that receives snapshots/orders via channel
    /// and writes them to the replay file. Crash-safe: payload is
    /// written first, header updated atomically after fsync (Fossilize
    /// pattern — see D010).
    writer: JoinHandle<()>,
    /// Channel to send tick orders to the writer.
    order_tx: Sender<RecordedTick>,
    /// Interval for full snapshot keyframes (default: every 300 ticks).
    snapshot_interval: u64,
}

pub struct RecordedTick {
    pub tick: u64,
    pub orders: TickOrders,
    /// Full snapshot at keyframe intervals; delta snapshot otherwise.
    /// Delta snapshots encode only changed components (see below).
    pub snapshot: Option<SnapshotType>,
}

pub enum SnapshotType {
    Full(SimSnapshot),
    Delta(DeltaSnapshot),
}
}

Per-Field Change Tracking (from Source Engine CNetworkVar)

To support delta snapshots efficiently, the sim uses per-field change tracking — inspired by Source Engine’s CNetworkVar system (see research/valve-github-analysis.md § 2.2). Each ECS component that participates in snapshotting is annotated with a #[track_changes] derive macro. The macro generates a companion bitfield that records which fields changed since the last snapshot. Delta serialization then skips unchanged fields entirely.

#![allow(unused)]
fn main() {
/// Derive macro that generates per-field change tracking for a component.
/// Each field gets a corresponding bit in a compact `ChangeMask` bitfield.
/// When a field is modified through its setter, the bit is set.
/// Delta serialization reads the mask to skip unchanged fields.
///
/// Components with SPROP_CHANGES_OFTEN (position, health, facing) are
/// checked first during delta computation — improves cache locality
/// by touching hot data before cold data. See `10-PERFORMANCE.md`.
#[derive(Component, Serialize, Deserialize, TrackChanges)]
pub struct Mobile {
    pub position: WorldPos,        // changes every tick during movement
    pub facing: FixedAngle,        // changes every tick during turning
    pub speed: FixedPoint,         // changes occasionally
    pub locomotor_type: Locomotor, // rarely changes
}

// Generated by #[derive(TrackChanges)]:
// impl Mobile {
//     pub fn set_position(&mut self, val: WorldPos) {
//         self.position = val;
//         self.change_mask |= 0b0001;
//     }
//     pub fn change_mask(&self) -> u8 { self.change_mask }
//     pub fn clear_changes(&mut self) { self.change_mask = 0; }
// }
}

SPROP_CHANGES_OFTEN priority (from Source Engine): Components that change frequently (position, health, ammunition) are tagged and processed first during delta encoding. This isn’t a correctness concern — it’s a cache locality optimization. By processing high-churn components first, the delta encoder touches frequently-modified memory regions while they’re still in L1/L2 cache. See 10-PERFORMANCE.md for performance impact analysis.

Crash-Time State Capture

When a desync is detected (hash mismatch via report_sync_hash()), the system automatically captures a full state snapshot before any error handling or recovery:

#![allow(unused)]
fn main() {
/// Called by NetworkModel when a sync hash mismatch is detected.
/// Captures full state immediately — before the sim advances further —
/// so the exact divergence point is preserved for offline analysis.
fn on_desync_detected(sim: &Simulation, tick: u64, local_hash: u64, remote_hash: u64) {
    // 1. Immediate full snapshot
    let snapshot = sim.snapshot();
    // 2. Write to crash dump file (same Fossilize append-safe pattern)
    write_crash_dump(tick, local_hash, remote_hash, &snapshot);
    // 3. If Merkle tree is available, capture the tree for
    //    logarithmic desync localization (see 03-NETCODE.md)
    if let Some(tree) = sim.merkle_tree() {
        write_merkle_dump(tick, &tree);
    }
    // 4. Continue with normal desync handling (reconnect, notify user, etc.)
}
}

This ensures desync debugging always has a snapshot at the exact point of divergence — not N ticks later when the developer gets around to analyzing it. The pattern comes from Valve’s Fossilize (crash-safe state capture, see research/valve-github-analysis.md § 3.1) and OpenTTD’s periodic desync snapshot naming convention (desync_{seed}_{tick}.snap).

Pathfinding & Spatial Queries

Pathfinding & Spatial Queries

Decision: Pathfinding and spatial queries are abstracted behind traits — like NetworkModel. A multi-layer hybrid pathfinder is the first implementation (RA1 game module). The engine core has no hardcoded assumption about grids vs. continuous space.

OpenRA uses hierarchical A* which struggles with large unit groups and lacks local avoidance. A multi-layer approach (hierarchical sectors + JPS/flowfield tiles + ORCA-lite avoidance) handles both small-group and mass unit movement. But pathfinding is a game-module concern, not an engine-core assumption.

Pathfinder Trait

#![allow(unused)]
fn main() {
/// Game modules implement this to provide pathfinding.
/// Grid-based games use multi-layer hybrid (JPS + flowfield tiles + avoidance).
/// Continuous-space games would use navmesh.
/// The engine core calls this trait — never a specific algorithm.
pub trait Pathfinder: Send + Sync {
    /// Request a path from origin to destination.
    /// Returns a local handle (`PathId`) used only inside the running sim instance.
    /// `PathId` is not part of network protocol or replay/save serialization.
    fn request_path(&mut self, origin: WorldPos, dest: WorldPos, locomotor: LocomotorType) -> PathId;

    /// Poll for completed path. Returns waypoints in WorldPos.
    fn get_path(&self, id: PathId) -> Option<&[WorldPos]>;

    /// Can a unit with this locomotor pass through this position?
    fn is_passable(&self, pos: WorldPos, locomotor: LocomotorType) -> bool;

    /// Invalidate cached paths (e.g., building placed, bridge destroyed).
    fn invalidate_area(&mut self, center: WorldPos, radius: SimCoord);

    /// Query the path distance between two points without computing full waypoints.
    /// Returns `None` if no path exists. Used by AI for target selection, threat assessment,
    /// and build placement scoring.
    fn path_distance(&self, from: WorldPos, to: WorldPos, locomotor: LocomotorType) -> Option<SimCoord>;

    /// Batch distance queries — amortizes overhead when AI needs distances to many targets.
    /// Writes results into caller-provided scratch (`out`) in the same order as `targets`.
    /// `None` entries mean no path. Implementations must clear/reuse `out` (no hidden heap scratch
    /// returned to the caller), preserving the zero-allocation hot-path discipline.
    /// Design informed by SC2's batch `RequestQueryPathing` (see `research/blizzard-github-analysis.md` § Part 4).
    fn batch_distances_into(
        &self,
        from: WorldPos,
        targets: &[WorldPos],
        locomotor: LocomotorType,
        out: &mut Vec<Option<SimCoord>>,
    );

    /// Convenience wrapper for non-hot paths (tools/debug/tests).
    /// Hot gameplay loops should prefer `batch_distances_into`.
    fn batch_distances(
        &self,
        from: WorldPos,
        targets: &[WorldPos],
        locomotor: LocomotorType,
    ) -> Vec<Option<SimCoord>> {
        let mut out = Vec::with_capacity(targets.len());
        self.batch_distances_into(from, targets, locomotor, &mut out);
        out
    }
}
}

SpatialIndex Trait

#![allow(unused)]
fn main() {
/// Game modules implement this for spatial queries (range checks, collision, targeting).
/// Grid-based games use a spatial hash grid. Continuous-space games could use BVH or R-tree.
/// The engine core queries this trait — never a specific data structure.
pub trait SpatialIndex: Send + Sync {
    /// Find all entities within range of a position.
    /// Writes results into caller-provided scratch (`out`) with deterministic ordering.
    /// Contract: for identical sim state + filter, the output order must be identical on all clients.
    /// Default recommendation is ascending `EntityId`, unless a stricter subsystem-specific contract exists.
    fn query_range_into(
        &self,
        center: WorldPos,
        range: SimCoord,
        filter: EntityFilter,
        out: &mut Vec<EntityId>,
    );

    /// Update entity position in the index.
    fn update_position(&mut self, entity: EntityId, old: WorldPos, new: WorldPos);

    /// Remove entity from the index.
    fn remove(&mut self, entity: EntityId);
}
}

Determinism, Snapshot, and Cache Rules (Pathfinding/Spatial)

The Pathfinder and SpatialIndex traits are algorithm seams, but they still operate under the simulation’s deterministic/snapshottable rules:

• Authoritative state lives in ECS/components, not only inside opaque pathfinder internals.
• Path IDs are local handles, not stable serialized identifiers.
• Derived caches (flowfield caches, sector caches, spatial buckets, temporary query results) may be omitted from snapshots and rebuilt on load/restore/reconnect.
• Pending path requests must be either:
  • represented in authoritative sim state, or
  • safely reconstructible deterministically on restore.
• Internal parallelism is allowed only if the visible outputs (paths, distances, query results) are deterministic and independent of worker scheduling/order.
• Validation/debug tooling may recompute caches from authoritative state (see 03-NETCODE.md cache validation) to detect missed invalidation bugs.

Why This Matters

This is the same philosophy as WorldPos.z — costs near-zero now, prevents rewrites later:

The RA1 game module registers three Pathfinder implementations — RemastersPathfinder, OpenRaPathfinder, and IcPathfinder (D045) — plus GridSpatialHash. The active pathfinder is selected via experience profiles (D045). A deferred/optional continuous-space game module would register NavmeshPathfinder and BvhSpatialIndex. The sim core calls the trait — it never knows which one is running. The same principle applies to fog, damage, AI, ranking, and validation — see D041 in decisions/09d-gameplay.md for the full trait definitions and rationale.

Platform Portability

Platform Portability

The engine must not create obstacles for any platform. Desktop is the primary dev target, but every architectural choice must be portable to browser (WASM), mobile (Android/iOS), and consoles without rework.

Player Data Directory (D061)

All player data lives under a single, self-contained directory. The structure is stable and documented — a manual copy of this directory is a valid (if crude) backup. The ic backup CLI provides a safer alternative using SQLite VACUUM INTO for consistent database copies. See decisions/09e/D061-data-backup.md for full rationale, backup categories, and cloud sync design.

<data_dir>/
├── config.toml              # Settings (D033 toggles, keybinds, render quality)
├── profile.db               # Identity, friends, blocks, privacy (D053)
├── achievements.db          # Achievement collection (D036)
├── gameplay.db              # Event log, replay catalog, save index, map catalog (D034)
├── telemetry.db             # Unified telemetry events (D031) — pruned at 100 MB
├── keys/
│   └── identity.key         # Ed25519 private key (D052) — recoverable via mnemonic seed phrase (D061)
├── communities/             # Per-community credential stores (D052)
│   ├── official-ic.db
│   └── clan-wolfpack.db
├── saves/                   # Save game files (.icsave)
├── replays/                 # Replay files (.icrep)
├── screenshots/             # PNG with IC metadata in tEXt chunks
├── workshop/                # Downloaded Workshop content (D030)
├── mods/                    # Locally installed mods
├── maps/                    # Locally installed maps
├── logs/                    # Engine log files (rotated)
└── backups/                 # Created by `ic backup create`

Platform-specific <data_dir> resolution:

Override with IC_DATA_DIR environment variable or --data-dir CLI flag. All path resolution is centralized in ic-paths (see § Crate Design Notes). All asset loading goes through Bevy’s asset system (rule 5 below) — the data directory is for player-generated content, not game assets.

Data & Backup UI (D061)

The in-game Settings → Data & Backup panel exposes backup, restore, cloud sync, and profile export — the GUI equivalent of the ic backup CLI. A Data Health summary shows identity key status, sync recency, backup age, and data folder size. Critical data is automatically protected by rotating daily snapshots (auto-critical-N.zip, 3-day retention) and optional platform cloud sync (Steam Cloud / GOG Galaxy).

First-launch flow integrates with D032’s experience profile selection:

1. New player: identity created automatically → 24-word recovery phrase displayed → cloud sync offer → backup reminder prompt
2. Returning player on new machine: cloud data detected → restore offer showing identity, rating, match count; or mnemonic seed recovery (enter 24 words); or manual restore from backup ZIP / data folder copy

Post-milestone toasts (same system as D030’s Workshop cleanup prompts) nudge players without cloud sync to back up after ranked matches, campaign completion, or tier promotions. See decisions/09e/D061-data-backup.md “Player Experience” for full UX mockups and scenario walkthroughs.

Portability Design Rules

1. Input is abstracted behind a trait. InputSource produces PlayerOrders — it knows nothing about mice, keyboards, touchscreens, or gamepads. The game loop consumes orders, not raw input events. Each platform provides its own InputSource implementation.

2. UI layout is responsive. No hardcoded pixel positions. The sidebar, minimap, and build queue use constraint-based layout that adapts to screen size and aspect ratio. Mobile/tablet may use a completely different layout (bottom bar instead of sidebar). ic-ui provides layout profiles, not a single fixed layout.

3. Click-to-world is abstracted behind a trait. Isometric screen→world (desktop), touch→world (mobile), and raycast→world (3D mod) all implement the same ScreenToWorld trait, producing a WorldPos. Grid-based game modules convert to CellPos as needed. No isometric math or grid assumption hardcoded in the game loop.

4. Render quality is configurable per device. FPS cap, particle density, post-FX toggles, resolution scaling, shadow quality — all runtime-configurable. Mobile caps at 30fps; desktop targets 60-240fps. The renderer reads a RenderSettings resource, not compile-time constants. Four render quality tiers (Baseline → Standard → Enhanced → Ultra) are auto-detected from wgpu::Adapter capabilities at startup. Tier 0 (Baseline) targets GL 3.3 / WebGL2 hardware — no compute shaders, no post-FX, CPU particle fallback, palette tinting for weather. Advanced Bevy rendering features (3D render modes, heavy post-FX, dynamic lighting) are optional layers, not baseline requirements; the classic 2D game must remain fully playable on no-dedicated-GPU systems that meet the downlevel hardware floor. See 10-PERFORMANCE.md § “GPU & Hardware Compatibility” for tier definitions and hardware floor analysis.

5. No raw filesystem I/O. All asset loading goes through Bevy’s asset system, never std::fs directly. Mobile and browser have sandboxed filesystems; WASM has no filesystem at all. Save games use platform-appropriate storage (e.g., localStorage on web, app sandbox on mobile).

6. App lifecycle is handled. Mobile and consoles require suspend/resume/save-on-background. The snapshottable sim makes this trivial — snapshot() on suspend, restore() on resume. This must be an engine-level lifecycle hook, not an afterthought.

7. Audio backend is abstracted. Bevy handles this, but no code should assume a specific audio API. Platform-specific audio routing (e.g., phone speaker vs headphones, console audio mixing policies) is Bevy’s concern.

Platform Target Matrix

Input Abstraction

#![allow(unused)]
fn main() {
/// Platform-agnostic input source. Each platform implements this.
pub trait InputSource {
    /// Drain pending player orders from whatever input device is active.
    fn drain_orders(&mut self, buf: &mut Vec<TimestampedOrder>);
    // Caller provides the buffer (reused across ticks — zero allocation on hot path)

    /// Optional: hint about input capabilities for UI adaptation.
    fn capabilities(&self) -> InputCapabilities;
}

pub struct InputCapabilities {
    pub has_mouse: bool,
    pub has_keyboard: bool,
    pub has_touch: bool,
    pub has_gamepad: bool,
    pub screen_size: ScreenClass,  // Phone, Tablet, Desktop, TV
}

pub enum ScreenClass {
    Phone,    // < 7" — bottom bar UI, large touch targets
    Tablet,   // 7-13" — sidebar OK, touch targets
    Desktop,  // 13"+ — full sidebar, mouse precision
    TV,       // 40"+ — large text, gamepad radial menus
}
}

ic-ui reads InputCapabilities to choose the appropriate layout profile. The sim never sees any of this.

Platform Installer / Setup Capability Split (D069)

The first-run setup wizard (D069) needs a platform capability view that is separate from raw input capabilities. This captures what the distribution channel / platform shell already handles (binary install/update/verify, cloud availability, file browsing constraints) so IC can avoid duplicating responsibilities.

#![allow(unused)]
fn main() {
pub enum PlatformInstallChannel {
    StoreSteam,
    StoreGog,
    StoreEpic,
    StandaloneDesktop,
    Browser,
    Mobile,
    Console,
}

pub struct PlatformInstallerCapabilities {
    pub channel: PlatformInstallChannel,
    pub platform_handles_binary_install: bool,
    pub platform_handles_binary_updates: bool,
    pub platform_exposes_verify_action: bool, // Steam/GOG-style "verify files"
    pub supports_cloud_sync_offer: bool,      // via PlatformServices or platform API
    pub supports_manual_folder_browse: bool,  // browser/mobile often restricted
    pub supports_background_downloads: bool,  // policy/OS dependent
}
}

ic-game (platform integration layer) populates PlatformInstallerCapabilities and injects it into ic-ui. The D069 setup wizard and maintenance flows use it to decide:

• whether to show platform verify guidance vs IC-side content repair only
• whether to offer manual folder browsing as a primary or fallback path
• whether to present a browser/mobile “setup assistant” variant instead of a desktop-style installer narrative

This preserves the platform-agnostic engine core while making setup UX platform-aware in a principled way.

UI Theme System (D032)

UI Theme System (D032)

The UI is split into two orthogonal concerns:

• Layout profiles — where things go. Driven by ScreenClass (Phone, Tablet, Desktop, TV). Handles sidebar vs bottom bar, touch target sizes, minimap placement, mobile minimap clusters (alerts + camera bookmark dock), and semantic UI anchor resolution (e.g., primary_build_ui maps to sidebar on desktop/tablet and build drawer on phone). One per screen class.
• Themes — how things look. Driven by player preference. Handles colors, chrome sprites, fonts, animations, menu backgrounds. Switchable at any time.

This split is also what enables cross-device tutorial prompts without duplicating tutorial content: D065 references semantic actions and UI aliases, and ic-ui resolves them through the active layout profile chosen from InputCapabilities.

Localization Directionality & RTL/BiDi Layout Contract

Localization support is not just “font coverage.” IC must correctly support bidirectional (BiDi) text, RTL scripts (Arabic/Hebrew), and locale-aware UI layout behavior anywhere translatable text appears (menus, HUD labels, subtitles, dialogue, campaign UI, editor docs/help, and communication labels).

#![allow(unused)]
fn main() {
pub enum UiLayoutDirection {
    Ltr,
    Rtl,
}

pub enum DirectionalUiAssetPolicy {
    MirrorInRtl,
    FixedOrientation,
}
}

Architectural rules (normative):

• Text rendering supports shaping + BiDi. The shared UI text renderer must correctly handle Arabic shaping, Hebrew/Arabic punctuation behavior, and mixed-script strings (RTL + LTR + numbers) for UI, subtitles/closed captions, and communication labels.
• Font support is script-aware, not just “Unicode-capable.” ThemeFonts captures the preferred visual style per role (menu/body/HUD/mono), while the renderer resolves locale/script-aware fallback chains so missing glyphs do not silently break localized or RTL UI.
• Layout direction is locale-driven by default. UI layout profiles resolve anchors/alignments from the active locale (LTR/RTL) and may expose a QA/testing override (Auto, LTR, RTL) without changing the locale itself.
• Mirroring is selective, not global. Menu/settings/profile/chat panels and many list/detail layouts usually mirror in RTL, but battlefield/world-space semantics (map orientation, minimap world mapping, world coordinates, faction symbols where direction carries meaning) are not blindly mirrored.
• Directional assets declare policy. Icons/arrows/ornaments that can flip for readability must declare MirrorInRtl; assets with gameplay or symbolic orientation must declare FixedOrientation.
• Avoid baked text in images. UI chrome/images should not contain baked translatable text where possible. If unavoidable, localized variants are required and must be selected through the same asset/theme pipeline.
• Communication display reuses the same renderer, with D059 safety filtering. Legitimate RTL/LTR message/label display is preserved; anti-spoof filtering (dangerous BiDi controls, abusive invisible chars) is handled at the D059 input/sanitization layer before order injection.
• Shaping, BiDi resolution, and fallback are separate responsibilities under one shared contract. The implementation may use separate components for shaping, BiDi resolution, and font fallback, but ic-ui owns the canonical behavior and tests so runtime/editor/chat surfaces remain consistent.
• Localization QA validates layout with fallback fonts. Mixed-script strings, subtitles, and marker labels must be tested for wrap, truncation, clipping, and baseline alignment across fallback fonts (not just glyph existence), with D038 localization tooling surfacing these checks before publish.

This contract keeps ic-ui platform-agnostic and ensures localization correctness is implemented once in shared rendering/layout code rather than patched per screen or per platform.

Smart Font Fallback & Text Shaping Strategy (Localization)

RTL and broad localization support require a font-system strategy, not a single “full Unicode” font choice.

Requirements (normative):

• Theme fonts define style intent; runtime resolves fallback chains. Themes choose the preferred look (Inter, JetBrains Mono, etc.) while ic-ui resolves locale/script-aware fallback fonts for glyph coverage and shaping compatibility.
• Fallback chains are role-aware. Menu/body/HUD/monospace roles may use different fallback stacks; monospaced surfaces must not silently fall back to proportional fonts unless explicitly allowed by the UI surface policy.
• Fallback behavior is deterministic at layout time. The same normalized text + locale/layout-direction inputs should produce the same line breaks/glyph runs across supported platforms, except for explicitly documented platform-stack differences that are regression-tested in M11.PLAT.BROWSER_MOBILE_POLISH.
• Directionality testing includes font fallback. QA/testing direction overrides (Auto, LTR, RTL) must exercise the active fallback stack so clipping, punctuation placement, and spacing regressions are caught before release.
• Open-source text-stack lessons are implementation guidance, not architecture lock-in. IC may learn from HarfBuzz/FriBidi/Pango/Godot/Qt patterns, but the canonical behavior remains defined by this contract and D038 localization preview tooling.

Theme Architecture

Themes are YAML + sprite sheets — Tier 1 mods, no code required.

#![allow(unused)]
fn main() {
pub struct UiTheme {
    pub name: String,
    pub chrome: ChromeAssets,    // 9-slice panels, button states, scrollbar sprites
    pub colors: ThemeColors,     // primary, secondary, text, highlights
    pub fonts: ThemeFonts,       // menu, body, HUD
    pub main_menu: MainMenuConfig,  // background image or shellmap, music, button layout
    pub ingame: IngameConfig,    // sidebar style, minimap border, build queue chrome
    pub lobby: LobbyConfig,     // panel styling, slot layout
}
}

Built-in Themes

All art assets are original creations — no assets copied from EA or OpenRA. These themes capture aesthetic philosophy, not specific artwork.

Shellmap System

Main menu backgrounds can be live battles — a real game map with scripted AI running behind the menu UI:

• Per-theme configuration: Classic uses a static image (faithful to 1996), Remastered/Modern use shellmaps
• Maps tagged visibility: shellmap are eligible — random selection on each launch
• Shellmaps define camera paths (pan, orbit, or fixed)
• Mods automatically get their own shellmaps

Per-Game-Module Defaults

Each GameModule provides a default_theme() — RA1 defaults to Classic, future modules default to whatever fits their aesthetic. Players override in settings. This pairs naturally with D019 (switchable balance presets): Classic balance + Classic theme = feels like 1996.

Community Themes

• Publishable to workshop (D030) as standalone resources
• Stack with gameplay mods — a WWII total conversion ships its own olive-drab theme
• An “OpenRA-inspired” community theme is a natural contribution

See decisions/09c-modding.md § D032 for full rationale, YAML schema, and legal notes on asset sourcing.

QoL & Gameplay Behavior Toggles (D033)

QoL & Gameplay Behavior Toggles (D033)

Every quality-of-life improvement from OpenRA and the Remastered Collection is individually toggleable — attack-move, multi-queue production, health bars, range circles, guard command, waypoint queuing, and dozens more. Built-in presets group toggles into coherent profiles:

Toggles are categorized as sim-affecting (production rules, unit commands — synced in lobby) or client-only (health bars, range circles — per-player preference). This split preserves determinism (invariant #1) while giving each player visual/UX freedom.

Experience Profiles

D019 (balance), D032 (theme), D033 (behavior), D043 (AI behavior), D045 (pathfinding feel), and D048 (render mode) are six independent axes that compose into experience profiles. Selecting “Vanilla RA” sets all six to classic in one click. Selecting “Iron Curtain” sets classic balance + modern theme + best QoL + enhanced AI + modern movement + HD graphics. After selecting a profile, any individual setting can still be overridden.

Mod profiles (D062) are a superset of experience profiles: they bundle the six experience axes WITH the active mod set and conflict resolutions into a single named, hashable object. A mod profile answers “what mods am I running AND how is the game configured?” in one saved YAML file. The profile’s fingerprint (SHA-256 of the resolved virtual asset namespace) enables single-hash compatibility checking in multiplayer lobbies. Switching profiles reconfigures both the mod set and experience settings in one action. Publishing a local mod profile via ic mod publish-profile creates a Workshop modpack (D030). See decisions/09c-modding.md § D062.

See decisions/09d/D033-qol-presets.md for the full toggle catalog, YAML schema, and sim/client split details. See D043 for AI behavior presets, D045 for pathfinding behavior presets, and D048 for switchable render modes.

Red Alert Experience Recreation Strategy

Red Alert Experience Recreation Strategy

Making IC feel like Red Alert requires more than loading the right files. The graphics, sounds, menu flow, unit selection, cursor behavior, and click feedback must recreate the experience that players remember — verified against the actual source code. We have access to four authoritative reference codebases. Each serves a different purpose.

Reference Source Strategy

The principle: Original RA tells us what the values ARE. Remastered tells us what a modern version SHOULD feel like. OpenRA tells us what the community EXPECTS. Bevy tells us how to BUILD it.

Visual Fidelity Checklist

These are the specific visual elements that make Red Alert look like Red Alert. Each must be verified against original source code constants, not guessed from screenshots.

Sprite Rendering Pipeline

Z-Order (Draw Order)

The draw order determines what renders on top of what. Getting this wrong makes the game look subtly broken — units clipping through buildings, shadows on top of vehicles, overlays behind walls. The canonical order (verified from original source and OpenRA):

Layer 0: Terrain tiles (ground)
Layer 1: Smudges (craters, scorch marks, oil stains)
Layer 2: Building bibs (paved foundations)
Layer 3: Building shadows + unit shadows
Layer 4: Buildings (sorted by Y position — southern buildings render on top)
Layer 5: Infantry (sub-cell positioned)
Layer 6: Vehicles / Ships (sorted by Y position)
Layer 7: Aircraft shadows (on ground)
Layer 8: Low-flying aircraft (sorted by Y position)
Layer 9: High-flying aircraft
Layer 10: Projectiles
Layer 11: Explosions / visual effects
Layer 12: Shroud / fog-of-war overlay
Layer 13: UI overlays (health bars, selection boxes, waypoint lines)

Within each layer, entities sort by Y-coordinate (south = higher draw order = renders on top). This is the standard isometric sort that prevents visual overlapping artifacts. Bevy’s sprite z-ordering maps to this layer system via Transform.translation.z.

Audio Fidelity Checklist

Red Alert’s audio is iconic — the EVA voice, unit responses, Hell March, the tesla coil zap. Audio fidelity requires matching the original game’s mixing behavior, not just playing the right files.

Sound Categories and Mixing

Original RA music system: The original game’s music was a straightforward sequential playlist. THEME.CPP manages a track list with per-theme attributes — each theme has a scenario owner (some tracks only play in certain missions) and a duration. In skirmish, the full soundtrack is available. In campaign, the scenario INI can specify a starting theme, but once playing, tracks advance sequentially and the player can pick from the jukebox in the options menu. There is no combat-detection system, no crossfades, and no dynamic intensity shifting. The Remastered Collection and OpenRA both preserve this simple jukebox model.

IC enhancement — dynamic situational music: While the original RA’s engine didn’t support dynamic music, IC’s engine and SDK treat dynamic situational music as a first-class capability. Frank Klepacki designed the RA soundtrack with gameplay tempo in mind — high-energy industrial during combat, ambient tension during build-up (see 13-PHILOSOPHY.md § Principle #11) — but the original engine didn’t act on this intent. IC closes that gap at the engine level.

ic-audio provides three music playback modes, selectable per game module, per mission, or per mod:

# audio/music_config.yaml
music_mode: dynamic               # "jukebox" | "sequential" | "dynamic"

# Jukebox mode (classic RA behavior):
jukebox:
  tracks: [BIGF226M, GRNDWIRE, HELLMARCH, MUDRA, JBURN_RG, TRENCHES, CC_THANG, WORKX_RG]
  order: sequential               # or "shuffle"
  loop: true

# Dynamic mode (IC engine feature — mood-tagged tracks with state-driven selection):
dynamic_playlist:
  ambient:
    tracks: [BIGF226M, MUDRA, JBURN_RG]
  build:
    tracks: [GRNDWIRE, WORKX_RG]
  combat:
    tracks: [HELLMARCH, TRENCHES, CC_THANG]
  tension:
    tracks: [RADIO2, FACE_THE_ENEMY]
  victory:
    tracks: [RREPORT]
  defeat:
    tracks: [SMSH_RG]
  crossfade_ms: 2000              # default crossfade between mood transitions
  combat_linger_s: 5              # stay in combat music 5s after last engagement

In dynamic mode, the engine monitors game state — active combat, base threat level, unit losses, objective progress — and crossfades between mood categories automatically. Designers tag tracks by mood; the engine handles transitions. No scripting required for basic dynamic music.

Three layers of control for mission/mod creators:

The scenario editor’s Music Playlist module (see decisions/09f/D038-scenario-editor.md “Dynamic Music”) exposes the full dynamic system visually — a designer drags tracks into mood buckets and previews transitions without writing code. The Music Trigger module handles scripted one-shot moments (“play Hell March when the tanks breach the wall”). Both emit standard Lua that modders can extend.

The music_mode setting defaults to dynamic under the iron_curtain experience profile and jukebox under the vanilla profile for RA1’s built-in soundtrack. Game modules and total conversions define their own default mode and mood-tagged playlists. This is Tier 1 YAML configuration — no recompilation, no Lua required for basic use.

Unit Voice System

Unit voice responses follow a specific pattern from the original game:

Implementation: Unit voice definitions live in mods/ra/rules/units/*.yaml alongside other unit data:

# In rules/units/vehicles.yaml
medium_tank:
  voices:
    select: [VEHIC1, REPORT1, YESSIR1]
    move: [ACKNO, AFFIRM1, MOVOUT1]
    attack: [AFFIRM1, YESSIR1]
    deny: [NEGAT1, CANTDO1]
  voice_interval: 200     # minimum ticks between voice responses (prevents spam)

UX Fidelity Checklist

These are the interaction patterns that make RA play like RA. Each is a combination of input handling, visual feedback, and audio feedback.

Core Interaction Loop

Sidebar System

The sidebar is the player’s primary interface and the most recognizable visual element of Red Alert’s UI. Three reference implementations exist:

IC’s sidebar is YAML-driven (D032 themes), supporting all three styles as switchable presets. The Classic theme recreates the 1996 layout. The Remastered theme matches the modernized layout. The default IC theme takes the best elements of both.

Credit counter animation: The original RA doesn’t jump to the new credit value — it counts up or down smoothly ($5000 → $4200 ticks down digit by digit). This is a small detail that contributes significantly to the game feel. IC replicates this with an interpolated counter in ic-ui.

Build queue clock-wipe: The clock-wipe animation (circular reveal showing build progress on the unit icon) is one of RA’s most distinctive UI elements. ic-render implements this as a shader that masks the icon with a circular wipe driven by build progress percentage.

Verification Method

How we know the recreation is accurate — not “it looks about right” but “we verified against source”:

Community verification: Phase 3 exit criteria include “feels like Red Alert to someone who’s played it before.” This is subjective but critical — IC will release builds to the community for feel testing well before feature-completeness. The community IS the verification instrument for subjective fidelity.

What Each Phase Delivers

First Runnable — Bevy Loading RA Resources

First Runnable — Bevy Loading Red Alert Resources

This section defines the concrete implementation path from “no code” to “a Bevy window rendering a Red Alert map with sprites on it.” It spans Phase 0 (format literacy) through Phase 1 (rendering slice) and produces the project’s first visible output — the milestone that proves the architecture works.

Why This Matters

The first runnable is the “Hello World” of the engine. Until a Bevy window opens and renders actual Red Alert assets, everything is theory. This milestone:

• Validates ra-formats. Can we actually parse .mix, .shp, .pal, .tmp into usable data?
• Validates the Bevy integration. Can we get RA sprites into Bevy’s rendering pipeline?
• Validates the isometric math. Can we convert grid coordinates to screen coordinates correctly?
• Generates community interest. “Red Alert map rendered faithfully in Rust at 4K 144fps” is the first public proof that IC is real.

What We CAN Reference From Existing Projects

We cannot copy code from OpenRA (C#) or the Remastered Collection (proprietary C# layer), but we can study their design decisions:

Implementation Steps

Step 1: ra-formats — Parse Everything (Weeks 1–2)

Build the ra-formats crate to read all Red Alert binary formats. This is pure Rust with zero Bevy dependency — a standalone library that other tools could use.

Deliverables:

Key implementation detail: MIX archives use a CRC32 hash of the filename (uppercased) as the lookup key — there’s no filename stored in the archive. ra-formats must include the hash function and a known-filename dictionary (from OpenRA’s global.mix filenames list) to resolve entries by name.

Test strategy: Parse every .mix from a stock Red Alert installation. Extract every .shp and verify frame counts match OpenRA’s sequences/*.yaml. Render every .pal as a 16×16 color grid PNG.

Step 2: Bevy Window + One Sprite (Week 3)

The “Hello RA” moment — a Bevy window opens and displays a single Red Alert sprite with the correct palette applied.

What this proves: ra-formats output can flow into Bevy’s Image / TextureAtlas pipeline. Palette-indexed sprites render correctly on a GPU.

Implementation:

1. Load conquer.mix → extract e1.shp (rifle infantry) and temperat.pal
2. Convert SHP frames to RGBA pixels by looking up each palette index in the .pal → produce a Bevy Image
3. Build a TextureAtlas from the frame images (Bevy’s sprite sheet system)
4. Spawn a Bevy SpriteSheetBundle entity and animate through the idle frames
5. Display in a Bevy window with a simple orthographic camera

Palette handling: At this stage, palette application happens on the CPU during asset loading (index → RGBA lookup). The GPU palette shader (for runtime player color remapping, palette cycling) comes in Phase 1 proper. CPU conversion is correct and simple — good enough for validation.

Player color remapping: Not needed yet. Just render with the default palette. Player colors (palette indices 80–95) are a Phase 1 concern.

Step 3: Load and Render an OpenRA Map (Weeks 4–5)

Parse .oramap files and render the terrain grid in correct isometric projection.

What this proves: The coordinate system works. Isometric math is correct. Theater palettes load. Terrain tiles tile without visible seams.

Implementation:

1. Parse .oramap (ZIP archive containing map.yaml + map.bin)
2. map.yaml defines: map size, tileset/theater, player definitions, actor placements
3. map.bin is the tile grid: each cell has a tile index + subtile index
4. Load the theater tileset (e.g., temperat.mix for Temperate) and its palette
5. For each cell in the grid, look up the terrain tile image and blit it at the correct isometric screen position

Isometric coordinate transform:

screen_x = (cell_x - cell_y) * tile_half_width
screen_y = (cell_x + cell_y) * tile_half_height

Where tile_half_width = 30 and tile_half_height = 15 for classic RA’s 60×30 diamond tiles (these values come from the original source and OpenRA). This is the CoordTransform defined in Phase 0’s architecture work.

Tile rendering order: Tiles render left-to-right, top-to-bottom in map coordinates. This is the standard isometric painter’s algorithm. In Bevy, this translates to setting Transform.translation.z based on the cell’s Y coordinate (higher Y = lower z = renders behind).

Map bounds and camera: The map defines a playable bounds rectangle within the total tile grid. Set the Bevy camera to center on the map and allow panning with arrow keys / edge scrolling. Zoom with scroll wheel.

Step 4: Sprites on Map + Idle Animations + Camera (Weeks 6–8)

Place unit and building sprites on the terrain grid. Animate idle loops. Implement camera controls.

What this proves: Sprites render at correct positions on the terrain. Z-ordering works (buildings behind units, shadows under vehicles). Animation timing matches the original game.

Implementation:

1. Read actor placements from map.yaml — each actor has a type name, cell position, and owner
2. Look up the actor’s sprite sequence from sequences/*.yaml (or the unit rules) — this gives the .shp filename, frame ranges for each animation, and facing count
3. For each placed actor, create a Bevy entity with:
   • SpriteSheetBundle using the actor’s sprite frames
   • Transform positioned at the isometric screen location of the actor’s cell
   • Z-order based on render layer (see § “Z-Order” above) and Y-position within layer
4. Animate idle sequences: advance frames at the timing specified in the sequence definition
5. Buildings: render the “make” animation’s final frame (fully built state)

Camera system:

At this stage, the minimap is a simple downscaled render of the full map — no player colors, no fog. Game-quality minimap rendering comes in Phase 3.

Z-order validation: Place overlapping buildings and units in a test map. Verify visually against a screenshot from OpenRA rendering the same map. The 13-layer z-order system (§ “Z-Order” above) must be correct at this step.

Step 5: Shroud, Fog-of-War, and Selection (Weeks 9–10)

Add the visual layers that make it feel like an actual game viewport rather than a debug renderer.

Shroud rendering: Unexplored areas are black. Explored-but-not-visible areas show terrain but dimmed (fog). The shroud layer renders on top of everything (z-layer 12). Shroud edges use smooth blending tiles (from the tileset) for clean boundaries. At this stage, shroud state is hardcoded (reveal a circle around the map center) — real fog computation comes in Phase 2 with FogProvider.

Selection box: Left-click-drag draws a selection rectangle. In isometric view, this is traditionally a diamond-shaped selection (rotated 45°) to match the grid orientation, though OpenRA uses a screen-aligned rectangle. IC supports both via QoL toggle (D033). Selected units show a health bar and selection bracket below them.

Cursor system: The cursor changes based on what it’s hovering over — move cursor on ground, select cursor on own units, attack cursor on enemies. This is the CursorContext system. At this stage, implement the visual cursor switching; the actual order dispatch (right-click → move command) is Phase 2 sim work.

Step 6: Sidebar Chrome — First Game-Like Frame (Weeks 11–12)

Assemble the classic RA sidebar layout to complete the visual frame. No functionality yet — build queues don’t work, credits don’t tick, radar doesn’t update. But the layout is in place.

What this proves: Bevy UI can reproduce the RA sidebar layout. Theme YAML (D032) drives the arrangement. The viewport resizes correctly when the sidebar is present.

Sidebar layout (Classic theme):

┌───────────────────────────────────────────┬────────────┐
│                                           │  RADAR     │
│                                           │  MINIMAP   │
│                                           ├────────────┤
│          GAME VIEWPORT                    │  CREDITS   │
│          (isometric map)                  │  $ 10000   │
│                                           ├────────────┤
│                                           │  POWER BAR │
│                                           │  ████░░░░  │
│                                           ├────────────┤
│                                           │  BUILD     │
│                                           │  QUEUE     │
│                                           │  [icons]   │
│                                           │  [icons]   │
│                                           │            │
├───────────────────────────────────────────┴────────────┤
│  STATUS BAR: selected unit info / tooltip              │
└────────────────────────────────────────────────────────┘

Implementation: Use Bevy UI (bevy_ui) for the sidebar layout. The sidebar is a fixed-width panel on the right. The game viewport fills the remaining space. Each sidebar section is a placeholder panel with correct sizing and positioning. The radar minimap shows the downscaled terrain render from Step 4. Build queue icons show static sprite images from the unit/building sequences.

Theme loading: Read a theme.yaml (D032) that defines: sidebar width, section heights, font, color palette, chrome sprite sheet references. At this stage, only the Classic theme exists — but the loading system is in place so future themes just swap the YAML.

Content Detection — Finding RA Assets

Before any of the above steps can run, the engine must locate the player’s Red Alert game files. IC never distributes copyrighted assets — it loads them from games the player already owns.

Detection sources (probed at first launch):

If no content source is found, the first-launch flow guides the player to either install the game from a platform they own it on, or point to existing files. IC does not download game files from the internet (legal boundary).

See 05-FORMATS.md § “Content Source Detection and Installed Asset Locations” for detailed source probing logic and the ContentSource enum.

Timeline Summary

Phase 0 exit: Steps 1–2 complete (parsers + one sprite in Bevy). Phase 1 exit: All six steps complete — any OpenRA RA map loads and renders with sprites, animations, camera, shroud, and sidebar layout at 144fps on mid-range hardware.

After Step 6, the rendering slice is done. The next work is Phase 2: making the units actually do things (move, shoot, die) in a deterministic simulation. See 08-ROADMAP.md § Phase 2.

Crate Dependency Graph

Crate Dependency Graph

ic-protocol  (shared types: PlayerOrder, TimestampedOrder)
    ↑
    ├── ic-sim      (depends on: ic-protocol, ra-formats)
    ├── ic-net      (depends on: ic-protocol; contains RelayCore library + relay-server binary)
    ├── ra-formats  (standalone — .mix, .shp, .pal, YAML)
    ├── ic-render   (depends on: ic-sim for reading state)
    ├── ic-ui       (depends on: ic-sim, ic-render; reads SQLite for player analytics — D034)
    ├── ic-audio    (depends on: ra-formats)
    ├── ic-script   (depends on: ic-sim, ic-protocol)
    ├── ic-ai       (depends on: ic-sim, ic-protocol; reads SQLite for adaptive difficulty — D034)
    ├── ic-llm      (depends on: ic-sim, ic-script, ic-protocol; reads SQLite for personalization — D034)
    ├── ic-paths    (standalone — platform path resolution, portable mode; wraps `app-path` crate)
    ├── ic-editor   (depends on: ic-render, ic-sim, ic-ui, ic-protocol, ra-formats, ic-paths; SDK binary — D038+D040)
    └── ic-game     (depends on: everything above EXCEPT ic-editor)

Critical boundary: ic-sim never imports from ic-net. ic-net never imports from ic-sim. They only share ic-protocol. ic-game never imports from ic-editor — the game and SDK are separate binaries that share library crates.

Storage boundary: ic-sim never reads or writes SQLite (invariant #1). Three crates are read-only consumers of the client-side SQLite database: ic-ui (post-game stats, career page, campaign dashboard), ic-llm (personalized missions, adaptive briefings, coaching), ic-ai (difficulty scaling, counter-strategy selection). Gameplay events are written by a Bevy observer system in ic-game, outside the deterministic sim. See D034 in decisions/09e-community.md.

Crate Design Notes

Most crates are self-explanatory from the dependency graph, but three that appear in the graph without dedicated design doc sections are detailed here.

ic-audio — Sound, Music, and EVA

ic-audio is a Bevy audio plugin that handles all game sound: effects, EVA voice lines, music playback, and ambient audio.

Responsibilities:

• Sound effects: Weapon fire, explosions, unit acknowledgments, UI clicks. Triggered by sim events (combat, production, movement) via Bevy observer systems.
• EVA voice system: Plays notification audio triggered by notification_system() events. Manages a priority queue — high-priority notifications (nuke launch, base under attack) interrupt low-priority ones. Respects per-notification cooldowns.
• Music playback: Three modes — jukebox (classic sequential/shuffle), sequential (ordered playlist), and dynamic (mood-tagged tracks with game-state-driven transitions and crossfade). Supports .aud (original RA format via ra-formats) and modern formats (OGG, WAV via Bevy). Theme-specific intro tracks (D032 — Hell March for Classic theme). Dynamic mode monitors combat, base threat, and objective state to select appropriate mood category. See § “Red Alert Experience Recreation Strategy” for full music system design and D038 in decisions/09f-tools.md for scenario editor integration.
• Spatial audio: 3D positional audio for effects — explosions louder when camera is near. Uses Bevy’s spatial audio with listener at GameCamera.position (see § “Camera System”).
• VoIP playback: Decodes incoming Opus voice frames from MessageLane::Voice and mixes them into the audio output. Handles per-player volume, muting, and optional spatial panning (D059 § Spatial Audio). Voice replay playback syncs Opus frames to game ticks.
• Ambient soundscapes: Per-biome ambient loops (waves for coastal maps, wind for snow maps). Weather system (D022) can modify ambient tracks.

Key types:

#![allow(unused)]
fn main() {
pub struct AudioEvent {
    pub sound: SoundId,
    pub position: Option<WorldPos>,  // None = non-positional (UI, EVA, music)
    pub volume: f32,
    pub priority: AudioPriority,
}

pub enum AudioPriority { Ambient, Effect, Voice, EVA, Music }

pub struct Jukebox {
    pub playlist: Vec<TrackId>,
    pub current: usize,
    pub shuffle: bool,
    pub repeat: bool,
    pub crossfade_ms: u32,
}
}

Format support: .aud (IMA ADPCM, via ra-formats decoder), .ogg, .wav, .mp3 (via Bevy/rodio). Audio backend is abstracted by Bevy — no platform-specific code in ic-audio.

Phase: Core audio (effects, EVA, music) in Phase 3. Spatial audio and ambient soundscapes in Phase 3-4.

ic-ai — Skirmish AI and Adaptive Difficulty

ic-ai provides computer opponents for skirmish and campaign, plus adaptive difficulty scaling.

Architecture: AI players run as Bevy systems that read visible game state and emit PlayerOrders through ic-protocol. The sim processes AI orders identically to human orders — no special privileges. AI has no maphack by default (reads only fog-of-war-revealed state), though campaign scripts can grant omniscience for specific AI players via conditions.

Internal structure — priority-based manager hierarchy: The default PersonalityDrivenAi (D043) uses the dominant pattern found across all surveyed open-source RTS AI implementations (see research/rts-ai-implementation-survey.md):

PersonalityDrivenAi
├── EconomyManager       — harvester assignment, power monitoring, expansion timing
├── ProductionManager    — share-based unit composition, priority-queue build orders, influence-map building placement
├── MilitaryManager      — attack planning, event-driven defense, squad management
└── AiState (shared)     — threat map, resource map, scouting memory

Key techniques: priority-based resource allocation (from 0 A.D. Petra), share-based unit composition (from OpenRA), influence maps for building placement (from 0 A.D.), tick-gated evaluation (from Generals/Petra), fuzzy engagement logic (from OpenRA), Lanchester-inspired threat scoring (from MicroRTS research). Each manager runs on its own tick schedule — cheap decisions (defense) every tick, expensive decisions (strategic reassessment) every 60 ticks. Total amortized AI budget: <0.5ms per tick for 500 units. All AI working memory is pre-allocated in AiScratch (zero per-tick allocation). Full implementation detail in D043 (decisions/09d-gameplay.md).

AI tiers (YAML-configured):

Key types:

#![allow(unused)]
fn main() {
/// AI personality — loaded from YAML, defines behavior parameters.
pub struct AiPersonality {
    pub name: String,
    pub build_order_priority: Vec<ActorId>,  // what to build first
    pub attack_threshold: i32,               // army value before attacking
    pub aggression: i32,                     // 0-100 scale
    pub expansion_tendency: i32,             // how eagerly AI expands
    pub micro_level: MicroLevel,             // None, Basic, Advanced
    pub tech_preference: TechPreference,     // Rush, Balanced, Tech
}

pub enum MicroLevel { None, Basic, Advanced }
pub enum TechPreference { Rush, Balanced, Tech }
}

Adaptive difficulty (D034 integration): ic-ai reads the client-side SQLite database (match history, player performance metrics) to calibrate AI difficulty. If the player has lost 5 consecutive games against “Normal” AI, the AI subtly reduces its efficiency. If the player is winning easily, the AI tightens its build order. This is per-player, invisible, and optional (can be disabled in settings).

Shellmap AI: A stripped-down AI profile specifically for menu background battles (D032 shellmaps). Prioritizes visually dramatic behavior over efficiency — large army clashes, diverse unit compositions, no early rushes. Runs with reduced tick budget since it shares CPU with the menu UI.

# ai/shellmap.yaml
shellmap_ai:
  personality:
    name: "Shellmap Director"
    aggression: 40
    attack_threshold: 5000     # build up large armies before engaging
    micro_level: basic
    tech_preference: balanced
    build_order_priority: [power_plant, barracks, war_factory, ore_refinery]
    dramatic_mode: true        # prefer diverse unit mixes, avoid cheese strategies
    max_tick_budget_us: 2000   # 2ms max per AI tick (shellmap is background)

Lua/WASM AI mods: Community can implement custom AI via Lua (Tier 2) or WASM (Tier 3). Custom AI implements the AiStrategy trait (D041) and is selectable in the lobby. The engine provides ic-ai’s built-in PersonalityDrivenAi as the default; mods can replace or extend it.

AiStrategy Trait (D041):

AiPersonality tunes parameters within a fixed decision algorithm. For modders who want to replace the algorithm entirely (neural net, GOAP planner, MCTS, scripted state machine), the AiStrategy trait abstracts the decision-making:

#![allow(unused)]
fn main() {
/// Game modules and mods implement this for AI opponents.
/// Default: PersonalityDrivenAi (behavior trees driven by AiPersonality YAML).
pub trait AiStrategy: Send + Sync {
    /// Called once per AI player per tick. Reads fog-filtered state, emits orders.
    fn decide(
        &mut self,
        player: PlayerId,
        view: &FogFilteredView,
        tick: u64,
    ) -> Vec<PlayerOrder>;

    /// Human-readable name for lobby display.
    fn name(&self) -> &str;

    /// Difficulty tier for UI categorization.
    fn difficulty(&self) -> AiDifficulty;

    /// Per-tick compute budget hint (microseconds). None = no limit.
    fn tick_budget_hint(&self) -> Option<u64>;
}
}

FogFilteredView ensures AI honesty — the AI sees only what its units see, just like a human player. Campaign scripts can grant omniscience via conditions. AI strategies are selectable in the lobby: “IC Default (Normal)”, “Workshop: Neural Net v2.1”, etc. See D041 in decisions/09d-gameplay.md for full rationale.

Phase: Basic skirmish AI (Easy/Normal) in Phase 4. Hard/Brutal + adaptive difficulty in Phase 5-6a.

ic-script — Lua and WASM Mod Runtimes

ic-script hosts the Lua and WASM mod execution environments. It bridges the stable mod API surface to engine internals via a compatibility adapter layer.

Architecture:

  Mod code (Lua / WASM)
        │
        ▼
  ┌─────────────────────────┐
  │  Mod API Surface        │  ← versioned, stable (D024 globals, WASM host fns)
  ├─────────────────────────┤
  │  ic-script              │  ← this crate: runtime management, sandboxing, adaptation
  ├─────────────────────────┤
  │  ic-sim + ic-protocol   │  ← engine internals (can change between versions)
  └─────────────────────────┘

Responsibilities:

• Lua runtime management: Initializes mlua with deterministic seed, registers all API globals (D024), enforces LuaExecutionLimits, manages per-mod Lua states.
• WASM runtime management: Initializes wasmtime with fuel metering, registers WASM host functions, enforces WasmExecutionLimits, manages per-mod WASM instances.
• Mod lifecycle: Load → initialize → per-tick callbacks → unload. Mods are loaded at game start (not hot-reloaded mid-game in multiplayer — determinism).
• Compatibility adapter: Translates stable mod API calls to current engine internals. When engine internals change, this adapter is updated — mods don’t notice. See 04-MODDING.md § “Compatibility Adapter Layer”.
• Sandbox enforcement: No filesystem, no network, no raw memory access. All mod I/O goes through the host API. Capability-based security per mod.
• Campaign state: Manages Campaign.* and Var.* state for branching campaigns (D021). Campaign variables are stored in save games.

Key types:

#![allow(unused)]
fn main() {
pub struct ScriptRuntime {
    pub lua_states: HashMap<ModId, LuaState>,
    pub wasm_instances: HashMap<ModId, WasmInstance>,
    pub api_version: ModApiVersion,
}

pub struct LuaState {
    pub vm: mlua::Lua,
    pub limits: LuaExecutionLimits,
    pub mod_id: ModId,
}

pub struct WasmInstance {
    pub instance: wasmtime::Instance,
    pub limits: WasmExecutionLimits,
    pub capabilities: ModCapabilities,
    pub mod_id: ModId,
}
}

Determinism guarantee: Both Lua and WASM execute at a fixed point in the system pipeline (trigger_system() step). All clients run the same mod code with the same game state at the same tick. Lua’s string hash seed is fixed. math.random() is replaced with the sim’s deterministic PRNG.

WASM determinism nuance: WASM execution is deterministic for integer and fixed-point operations, but the WASM spec permits non-determinism in floating-point NaN bit patterns. If a WASM mod uses f32/f64 internally (which is legal — the sim’s fixed-point invariant applies to ic-sim Rust code, not to mod-internal computation), different CPU architectures may produce different NaN payloads, causing deterministic divergence (desync). Mitigations:

• Runtime mandate: IC uses wasmtime exclusively. All clients use the same wasmtime version (engine-pinned). wasmtime canonicalizes NaN outputs for WASM arithmetic operations, which eliminates NaN bit-pattern divergence across platforms.
• Defensive recommendation for mod authors: Mod development docs recommend using integer/fixed-point arithmetic for any computation whose results feed back into PlayerOrders or are returned to host functions. Floats are safe for mod-internal scratch computation that is consumed and discarded within the same call (e.g., heuristic scoring, weight calculations that produce an integer output).
• Hash verification: All clients verify the WASM binary hash (SHA-256) before game start. Combined with wasmtime’s NaN canonicalization and identical inputs, this provides a strong determinism guarantee — but it is not formally proven the way ic-sim’s integer-only invariant is. WASM mod desync is tracked as a distinct diagnosis path in the desync debugger.

Browser builds: Tier 3 WASM mods are desktop/server-only. The browser build (WASM target) cannot embed wasmtime — see 04-MODDING.md § “Browser Build Limitation (WASM-on-WASM)” for the full analysis and the documented mitigation path (wasmi interpreter fallback), which is an optional browser-platform expansion item unless promoted by platform milestone requirements.

Phase: Lua runtime in Phase 4. WASM runtime in Phase 4-5. Mod API versioning in Phase 6a.

ic-paths — Platform Path Resolution and Portable Mode

ic-paths is the single crate responsible for resolving all filesystem paths the engine uses at runtime: the player data directory (D061), log directory, mod search paths, and install-relative asset paths. Every other crate that needs a filesystem location imports from ic-paths — no crate resolves platform paths on its own.

Two modes:

Mode is selected by (highest priority first):

1. IC_PORTABLE=1 environment variable
2. --portable CLI flag
3. Presence of a portable.marker file next to the executable
4. Otherwise: platform mode

Portable mode uses the app-path crate (zero-dependency, cross-platform exe-relative path resolution with static caching) to resolve all paths relative to the executable. In portable mode the data directory becomes <exe_dir>/data/ instead of the platform-specific location, and the entire installation is self-contained — copy the folder to move it.

Key types:

#![allow(unused)]
fn main() {
/// Resolved set of root paths for the current session.
/// Computed once at startup, immutable thereafter.
pub struct AppDirs {
    pub data_dir: PathBuf,      // Player data (D061): config, saves, replays, keys, ...
    pub install_dir: PathBuf,   // Shipped content: mods/common/, mods/ra/, binaries
    pub log_dir: PathBuf,       // Log files (rotated)
    pub cache_dir: PathBuf,     // Temporary/derived data (shader cache, download staging)
    pub mode: PathMode,         // Platform or Portable — for diagnostics / UI display
}

pub enum PathMode { Platform, Portable }
}

Additional override: --data-dir <path> CLI flag overrides the data directory location regardless of mode. This is useful for developers running multiple profiles or testing with different data sets. If --data-dir is set, PathMode is still reported as Platform or Portable based on the detection above — the override only changes data_dir, not the mode label.

Visibility: The current path mode is shown in:

• Settings → Data tab: "Data location: C:\Games\IC\data\ (portable mode)" or "Data location: %APPDATA%\IronCurtain\ (standard)"
• Console: ic_paths command prints all resolved paths and the active mode
• First-launch wizard: if portable mode is detected, a brief note: "Running in portable mode — all data is stored next to the game executable."
• Main menu footer (optional, subtle): a small [P] badge or "Portable" label if the player wants to see it (toggleable via Settings → Video → Show Mode Indicator)

Creating a portable installation: To convert a standard install into a portable one, a user just:

1. Copies the game folder to a USB drive (or any location)
2. Creates an empty portable.marker file next to the executable
3. Launches the game — done

No explicit init step needed. On first launch in portable mode, the engine auto-creates the data/ directory and runs the first-launch wizard normally. If the user already has a platform install on the same machine, the wizard detects it and offers: "Found existing IC data on this machine. [Import my settings & identity] [Start fresh]". This replaces any need for a separate init command — the wizard handles everything, and the user doesn’t need to learn a CLI command to set up portable mode.

WASM: Browser builds return OPFS-backed virtual paths. Portable mode is not applicable — PathMode::Platform is always used. Mobile builds use the platform app sandbox unconditionally.

Phase: Phase 1 (required before any file I/O — asset loading, config, logs).

Install & Source Layout

Install & Source Layout (Community-Friendly Project Structure)

The directory structure — both the shipped product and the source repository — is designed to feel immediately navigable to anyone who has worked with OpenRA. OpenRA’s modding community thrived because the project was approachable: open a mod folder, find YAML rules organized by category, edit values, see results. IC preserves that muscle memory while fitting the structure to a Rust/Bevy codebase.

Design Principles

1. Game modules are mods. Built-in game modules (mods/ra/, mods/td/) use the exact same directory layout, mod.yaml manifest, and YAML rule schema as community-created mods. No internal-only APIs, no special paths. If a modder can edit mods/ra/rules/units/vehicles.yaml, anyone can see how the game’s own data is structured. Directly inspired by Factorio’s “game is a mod” principle (validated in D018).

2. Same vocabulary, same directories. OpenRA uses rules/, sequences/, chrome/, maps/, audio/, scripts/. IC uses the same directory names for the same purposes. An OpenRA modder opening IC’s mods/ra/ directory knows where everything is.

3. Separate binaries for separate roles. Game client, dedicated server, CLI tool, and SDK editor are separate executables — like OpenRA ships OpenRA.exe, OpenRA.Server.exe, and OpenRA.Utility.exe. A server operator never needs the renderer. A modder using the SDK never needs the multiplayer client. Each has its own binary, sharing library crates underneath.

4. Flat and scannable. No deep nesting for its own sake. A modder looking at mods/ra/ should see the high-level structure in a single ls. Subdirectories within rules/ organize by category (units, structures, weapons) — the same pattern OpenRA uses.

5. Data next to data, code next to code. Game content (YAML, Lua, assets) lives in mods/. Engine code (Rust) lives in crate directories. They don’t intermingle. A gameplay modder never touches Rust. A engine contributor goes straight to the crate they need.

Install Directory (Shipped Product)

What an end user sees after installing Iron Curtain:

iron-curtain/
├── iron-curtain[.exe]              # Game client (ic-game binary)
├── ic-server[.exe]                 # Relay / dedicated server (ic-net binary)
├── ic[.exe]                        # CLI tool (mod, backup, export, profile, server commands)
├── ic-editor[.exe]                 # SDK: scenario editor, asset studio, campaign editor (D038+D040)
├── mods/                           # Game modules + content — the heart of the project
│   ├── common/                     # Shared resources used by all C&C-family modules
│   │   ├── mod.yaml                #   manifest (declares shared chrome, cursors, etc.)
│   │   ├── chrome/                 #   shared UI layout definitions
│   │   ├── cursors/                #   shared cursor definitions
│   │   └── translations/           #   shared localization strings
│   ├── ra/                         # Red Alert game module (ships Phase 2)
│   │   ├── mod.yaml                #   manifest — same schema as any community mod
│   │   ├── rules/                  #   unit, structure, weapon, terrain definitions
│   │   │   ├── units/              #     infantry.yaml, vehicles.yaml, naval.yaml, aircraft.yaml
│   │   │   ├── structures/         #     allied-structures.yaml, soviet-structures.yaml
│   │   │   ├── weapons/            #     ballistics.yaml, missiles.yaml, energy.yaml
│   │   │   ├── terrain/            #     temperate.yaml, snow.yaml, interior.yaml
│   │   │   └── presets/            #     balance presets: classic.yaml, openra.yaml, remastered.yaml (D019)
│   │   ├── maps/                   #   built-in maps
│   │   ├── missions/               #   campaign missions (YAML scenario + Lua triggers)
│   │   ├── sequences/              #   sprite sequence definitions (animation frames)
│   │   ├── chrome/                 #   RA-specific UI layout (sidebar, build queue)
│   │   ├── audio/                  #   music playlists, EVA definitions, voice mappings
│   │   ├── ai/                     #   AI personality profiles (D043)
│   │   ├── scripts/                #   Lua scripts (shared triggers, ability definitions)
│   │   └── themes/                 #   UI theme overrides: classic.yaml, modern.yaml (D032)
│   └── td/                         # Tiberian Dawn game module (ships Phase 3–4)
│       ├── mod.yaml
│       ├── rules/
│       ├── maps/
│       ├── missions/
│       └── ...                     #   same layout as ra/
├── LICENSE
└── THIRD-PARTY-LICENSES

Key features of the install layout:

• mods/common/ is directly analogous to OpenRA’s mods/common/. Shared assets, chrome, and cursor definitions used across all C&C-family game modules. Community game modules (Dune 2000, RA2) can depend on it or provide their own.
• mods/ra/ is a mod. It uses the same mod.yaml schema, the same rules/ structure, and the same sequences/ format as a community mod. There is no “privileged” version of this directory — the engine treats it identically to <data_dir>/mods/my-total-conversion/. This means every modder can read the game’s own data as a working example.
• Every YAML file in mods/ra/rules/ is editable. Want to change tank cost? Open rules/units/vehicles.yaml, find medium_tank, change cost: 800 to cost: 750. The same workflow as OpenRA — except the YAML is standard-compliant and serde-typed.
• The CLI (ic) is the Swiss Army knife. ic mod init, ic mod check, ic mod test, ic mod publish, ic backup create, ic export, ic server validate-config. One binary, consistent subcommands — no separate tools to discover.

Source Repository (Contributor Layout)

What a contributor sees after cloning the repository:

iron-curtain/                       # Cargo workspace root
├── Cargo.toml                      # Workspace manifest — lists all crates
├── Cargo.lock
├── deny.toml                       # cargo-deny license policy (GPL-compatible deps only)
├── AGENTS.md                       # Agent instructions (this file)
├── README.md
├── LICENSE                         # GPL v3 with modding exception (D051)
├── mods/                           # Game data — YAML, Lua, assets (NOT Rust code)
│   ├── common/
│   ├── ra/
│   └── td/
├── crates/                         # All Rust crates live here
│   ├── ra-formats/                 # .mix, .shp, .pal parsers; MiniYAML converter
│   │   ├── Cargo.toml
│   │   └── src/
│   │       ├── lib.rs
│   │       ├── mix.rs              #   MIX archive reader
│   │       ├── shp.rs              #   SHP sprite reader
│   │       ├── pal.rs              #   PAL palette reader
│   │       ├── aud.rs              #   AUD audio decoder
│   │       ├── vqa.rs              #   VQA video decoder
│   │       ├── miniyaml.rs         #   MiniYAML parser + converter (D025)
│   │       ├── oramap.rs           #   .oramap map loader
│   │       └── mod_manifest.rs     #   OpenRA mod.yaml parser (D026)
│   ├── ic-protocol/                # Shared boundary: orders, codecs
│   │   ├── Cargo.toml
│   │   └── src/
│   │       ├── lib.rs
│   │       ├── orders.rs           #   PlayerOrder, TimestampedOrder
│   │       └── codec.rs            #   OrderCodec trait
│   ├── ic-sim/                     # Deterministic simulation (the core)
│   │   ├── Cargo.toml
│   │   └── src/
│   │       ├── lib.rs              #   pub API: Simulation, step(), snapshot()
│   │       ├── components/         #   ECS components — one file per domain
│   │       │   ├── mod.rs
│   │       │   ├── health.rs       #     Health, Armor, DamageState
│   │       │   ├── mobile.rs       #     Mobile, Locomotor, Facing
│   │       │   ├── combat.rs       #     Armament, AutoTarget, Turreted, AmmoPool
│   │       │   ├── production.rs   #     Buildable, ProductionQueue, Prerequisites
│   │       │   ├── economy.rs      #     Harvester, ResourceStorage, OreField
│   │       │   ├── transport.rs    #     Cargo, Passenger, Carryall
│   │       │   ├── power.rs        #     PowerProvider, PowerConsumer
│   │       │   ├── stealth.rs      #     Cloakable, Detector
│   │       │   ├── capture.rs      #     Capturable, Captures
│   │       │   ├── veterancy.rs    #     Veterancy, Experience
│   │       │   ├── building.rs     #     Placement, Foundation, Sellable, Repairable
│   │       │   └── support.rs      #     Superweapon, Chronoshift, IronCurtain
│   │       ├── systems/            #   ECS systems — one file per simulation step
│   │       │   ├── mod.rs
│   │       │   ├── orders.rs       #     validate_orders(), apply_orders()
│   │       │   ├── movement.rs     #     movement_system() — pathfinding integration
│   │       │   ├── combat.rs       #     combat_system() — targeting, firing, damage
│   │       │   ├── production.rs   #     production_system() — build queues, prerequisites
│   │       │   ├── harvesting.rs   #     harvesting_system() — ore collection, delivery
│   │       │   ├── power.rs        #     power_system() — grid calculation
│   │       │   ├── fog.rs          #     fog_system() — delegates to FogProvider trait
│   │       │   ├── triggers.rs     #     trigger_system() — Lua/WASM script callbacks
│   │       │   ├── conditions.rs   #     condition_system() — D028 condition evaluation
│   │       │   ├── cleanup.rs      #     cleanup_system() — entity removal, state transitions
│   │       │   └── weather.rs      #     weather_system() — D022 weather state machine
│   │       ├── traits/             #   Pluggable abstractions (D041) — NOT OpenRA "traits"
│   │       │   ├── mod.rs
│   │       │   ├── pathfinder.rs   #     Pathfinder trait (D013)
│   │       │   ├── spatial.rs      #     SpatialIndex trait
│   │       │   ├── fog.rs          #     FogProvider trait
│   │       │   ├── damage.rs       #     DamageResolver trait
│   │       │   ├── validator.rs    #     OrderValidator trait (D041)
│   │       │   └── ai.rs           #     AiStrategy trait (D041)
│   │       ├── math/               #   Fixed-point arithmetic, coordinates
│   │       │   ├── mod.rs
│   │       │   ├── fixed.rs        #     Fixed-point types (i32/i64 scale — P002)
│   │       │   └── pos.rs          #     WorldPos, CellPos
│   │       ├── rules/              #   YAML rule deserialization (serde structs)
│   │       │   ├── mod.rs
│   │       │   ├── unit.rs         #     UnitDef, Buildable, DisplayInfo
│   │       │   ├── weapon.rs       #     WeaponDef, Warhead, Projectile
│   │       │   ├── alias.rs        #     OpenRA trait name alias registry (D023)
│   │       │   └── inheritance.rs  #     YAML inheritance resolver
│   │       └── snapshot.rs         #   State serialization for saves/replays/rollback
│   ├── ic-net/                     # Networking (never imports ic-sim)
│   │   ├── Cargo.toml
│   │   └── src/
│   │       ├── lib.rs
│   │       ├── network_model.rs    #   NetworkModel trait (D006)
│   │       ├── lockstep.rs         #   LockstepNetwork implementation
│   │       ├── local.rs            #   LocalNetwork (testing, single-player)
│   │       ├── relay_core.rs       #   RelayCore library (D007)
│   │       └── bin/
│   │           └── relay.rs        #   relay-server binary entry point
│   ├── ic-render/                  # Isometric rendering (Bevy plugin)
│   ├── ic-ui/                      # Game chrome, sidebar, minimap
│   ├── ic-audio/                   # Sound, music, EVA, VoIP
│   ├── ic-script/                  # Lua + WASM mod runtimes
│   ├── ic-ai/                      # Skirmish AI, adaptive difficulty
│   ├── ic-llm/                     # LLM mission generation (optional)
│   ├── ic-paths/                   # Platform path resolution, portable mode (wraps `app-path`)
│   ├── ic-editor/                  # SDK binary: scenario editor, asset studio (D038+D040)
│   └── ic-game/                    # Game binary: ties all plugins together
│       ├── Cargo.toml
│       └── src/
│           └── main.rs             #   Bevy App setup, plugin registration
├── tools/                          # Developer tools (not shipped)
│   ├── miniyaml2yaml/              #   MiniYAML → YAML batch converter CLI
│   └── replay-corpus/              #   Foreign replay regression test harness (D056)
└── tests/                          # Integration tests
    ├── sim/                        #   Deterministic sim regression tests
    └── format/                     #   File format round-trip tests

Where OpenRA Contributors Find Things

An OpenRA contributor’s first question is “where does this live in IC?” This table maps OpenRA’s C# project structure to IC’s Rust workspace:

ECS Translation: OpenRA Traits → IC Components + Systems

OpenRA merges data and behavior into “traits” (C# classes). In IC’s ECS architecture, these split into components (data) and systems (behavior):

The naming convention follows Rust idioms (snake_case files, PascalCase types) but the organization mirrors OpenRA’s categorical grouping — combat things together, economy things together, movement things together.

Why This Layout Works for the Community

For data modders (80% of mods): Never leave mods/. Edit YAML, run ic mod check, see results. The built-in game modules serve as always-available, documented examples of every YAML feature. No need to read Rust code to understand what fields a unit definition supports — look at mods/ra/rules/units/infantry.yaml.

For Lua scripters (missions, game modes): Write scripts/*.lua in your mod directory. The API is a superset of OpenRA’s (D024) — same 16 globals, same function signatures. Existing OpenRA missions run unmodified. Test with ic mod test.

For engine contributors: Clone the repo. crates/ holds all Rust code. Each crate has a single responsibility and clear boundaries. The naming (ic-sim, ic-net, ic-render) tells you what it does. Within ic-sim, components/ holds data, systems/ holds logic, traits/ holds the pluggable abstractions — the ECS split is consistent and predictable.

For total-conversion modders: The ic-sim/src/traits/ directory defines every pluggable seam — custom pathfinder, custom AI, custom fog of war, custom damage resolution. Implement a trait as a WASM module (Tier 3), register it in your mod.yaml, and the engine uses your implementation. No forking, no C# DLL stacking.

Development Asset Strategy

A clean-sheet engine needs art for editor chrome, UI menus, CI testing, and developer workflows — but it cannot ship or commit copyrighted game content. This subsection documents how reference projects host their game resources, what IC can freely use, and what belongs (or doesn’t belong) in the repository.

How Reference Projects Host Game Resources

Original Red Alert (1996): Assets ship as .mix archives — flat binary containers with CRC-hashed filenames. Originally distributed on CD-ROM, later as a freeware download installer (2008). All sprites (.shp), terrain (.tmp), palettes (.pal), audio (.aud), and cutscenes (.vqa) are packed inside these archives. No separate asset repository — everything distributes as compiled binaries through retail channels. The freeware release means free to download and play, not free to redistribute or embed in another project.

EA Remastered Collection (2020): Assets distribute through Steam (and previously Origin). The HD sprite sheets, remastered music, and cutscenes are proprietary EA content — not covered by the GPL v3 license that applies only to the C++ engine DLLs. Resources use updated archive formats (MegV3 for TD HD, standard .mix for classic mode) at known Steam AppId paths. See § Content Detection for how IC locates these.

OpenRA: The engine never distributes copyrighted game assets. On first launch, a content installer detects existing game installations (Steam, Origin, GOG, disc copies) or downloads specific .mix files from EA’s publicly accessible mirrors (the freeware releases). Assets are extracted and stored to ~/.openra/Content/ra/ (Linux) or the OS-appropriate equivalent. The OpenRA source repository contains only engine code (C#, GPL v3), original UI chrome art, mod rules (MiniYAML), maps, Lua scripts, and editor art — all OpenRA-created content. The few original assets (icons, cursors, fonts, panel backgrounds) are small enough for plain git. No Git LFS, no external asset hosting.

Key pattern: Every successful engine reimplementation project (OpenRA, CorsixTH, OpenMW, Wargus) uses the same model — engine code in the repo, game content loaded at runtime from the player’s own installation. IC follows this pattern exactly.

Legal Boundaries — What IC Can Freely Use

OpenRA’s original chrome art is technically GPL v3 and could be used — but IC’s design explicitly creates all theme art as original work (D032). Copying OpenRA’s chrome would create visual confusion between the two projects and contradict the design direction. Study the patterns (layout structure, what elements exist), create original art.

The EA GPL source repositories contain no art assets whatsoever — only C/C++ source code. The .mix archives containing actual game content (sprites, audio, palettes, terrain, cutscenes) are copyrighted EA property distributed through retail channels, even in the freeware release.

What Belongs in the Repository

Git LFS is not needed. The design docs already rejected Git LFS for Workshop distribution (“1GB free then paid; designed for source code, not binary asset distribution; no P2P” — see D049). The same reasoning applies to development: IC’s repository is code + YAML + design docs + small original icons. Total committed binary assets will stay well under 10MB.

CI testing strategy: Parser and format tests use synthetic fixtures — small, hand-crafted binary files (a 2-frame .shp, a trivial .mix with 3 files, a minimal .pal) committed to tests/fixtures/. These are original creations that exercise ra-formats code without containing EA content. Integration tests requiring real RA assets are gated behind an optional feature flag (#[cfg(feature = "integration")]) and run on CI runners where RA is installed, configured via IC_CONTENT_DIR environment variable.

Repository Asset Layout

Extending the source repository layout (see § Source Repository above):

iron-curtain/
├── assets/                         # IC-original assets ONLY (committed)
│   ├── editor/                     #   SDK toolbar icons, editor cursors, panel art
│   ├── ui/                         #   Menu chrome sprites, HUD elements
│   ├── fonts/                      #   Bundled open-licensed fonts
│   └── placeholder/                #   Debug sprites, test palettes, grid overlays
├── tests/
│   └── fixtures/                   #   Synthetic .mix/.shp/.pal for parser tests
├── content/                        #   *** GIT-IGNORED *** — local dev game files
│   └── ra/                         #   Developer's RA installation (pointed to or symlinked)
├── .gitignore                      #   Ignores content/, target/, *.db
└── ...

The content/ directory is git-ignored. Each developer either symlinks it to their RA installation or sets IC_CONTENT_DIR to point elsewhere. This keeps copyrighted assets completely out of version control while giving developers a consistent local path for testing.

Freely-Usable Resources for Graphics, Menus & CI

IC needs original art for editor chrome, UI menus, and visual tooling. These are the recommended open-licensed sources:

Icon libraries (for editor toolbar, SDK panels, menu items):

Fonts (for UI text, editor panels, console):

Smart font support note (localization/RTL):

• Primary UI fonts (theme-driven) and fallback fonts (coverage-driven) are distinct concerns.
• A broad-coverage family such as Noto should be available as the fallback backbone for scripts not covered by the theme’s primary font.
• Correct RTL rendering still depends on the shared shaping + BiDi + layout-direction contract above; fallback fonts alone are insufficient.

UI framework:

• egui (MIT) — the editor’s panel/widget framework. Ships with Bevy via bevy_egui. Provides buttons, sliders, text inputs, dropdown menus, tree views, docking, color pickers — all rendered procedurally with no external art needed. Handles 95% of SDK chrome requirements.
• Bevy UI — the game client’s UI framework. Used for in-game chrome (sidebar, minimap, build queue) with IC-original sprite sheets styled per theme (D032).

Game content (sprites, terrain, audio, cutscenes):

• Player’s own RA installation — loaded at runtime via ContentDetector. Every developer needs Red Alert installed locally (Steam, GOG, or freeware). This is the development workflow, not a limitation — you’re building an engine for a game you play.
• No external asset CDN. IC does not host, mirror, or download copyrighted game files. The browser build (Phase 7) uses drag-and-drop import from the player’s local files — see 05-FORMATS.md § Browser Asset Storage.

Placeholder art (for development before real assets load):

During early development, before the full content detection pipeline is complete, use committed placeholder assets in assets/placeholder/:

• Colored rectangles (16×16, 24×24, 48×48) as unit stand-ins
• Numbered grid tiles for terrain testing
• Solid-color palette files (.pal-format, 768 bytes) for render pipeline testing
• Simple geometric shapes for building footprints
• Generated checkerboard patterns for missing texture fallbacks

These are all original creations — trivial to produce, zero legal risk, and immediately useful for testing the render pipeline before content detection is wired up.

IC SDK & Editor Architecture (D038 + D040)

IC SDK & Editor Architecture (D038 + D040)

The IC SDK is the creative toolchain — a separate Bevy application that shares library crates with the game but ships as its own binary. Players never see editor UI. Creators download the SDK to build maps, missions, campaigns, and assets. This section covers the practical architecture: what the GUI looks like, what graphical resources it uses, how the UX flows, and how to start building it. For the full feature catalog (30+ modules, trigger system, campaign editor, dialogue trees, Game Master mode), see decisions/09f/D038-scenario-editor.md and decisions/09f/D040-asset-studio.md.

SDK Application Structure

The SDK is a single Bevy application with tabbed workspaces:

┌───────────────────────────────────────────────────────────────────────┐
│  IC SDK                                              [_][□][X]        │
├──────────────┬────────────────────────────────────────────────────────┤
│              │  [Scenario Editor] [Asset Studio] [Campaign Editor]    │
│  MODE PANEL  ├────────────────────────────────────────┬───────────────┤
│              │                                        │               │
│  ┌─────────┐ │         ISOMETRIC VIEWPORT             │  PROPERTIES   │
│  │Terrain  │ │                                        │  PANEL        │
│  │Entities │ │    (same ic-render as the game —       │               │
│  │Triggers │ │     live preview of actual game        │  [Name: ___]  │
│  │Waypoints│ │     rendering)                         │  [Faction: _] │
│  │Modules  │ │                                        │  [Health: __] │
│  │Regions  │ │                                        │  [Script: _]  │
│  │Scripts  │ │                                        │               │
│  │Layers   │ │                                        │               │
│  └─────────┘ │                                        │               │
│              ├────────────────────────────────────────┤               │
│              │  BOTTOM PANEL (context-sensitive)       │               │
│              │  Triggers list / Script editor / Vars  │               │
│              ├────────────────────────────────────────┴───────────────┤
│              │  STATUS BAR: cursor pos │ cell info │ complexity meter │
└──────────────┴───────────────────────────────────────────────────────┘

Four main areas:

GUI Technology Choice

The SDK faces a UI technology decision that the game does not: the game’s UI is a themed, styled chrome layer (D032) built for immersion, while the SDK needs a dense, professional tool UI with text fields, dropdowns, tree views, scrollable lists, and property inspectors.

Approach: Dual UI — ic-render viewport + egui panels

Why egui for tool panels: Bevy UI (bevy_ui) is designed for game chrome — styled panels, themed buttons, responsive layouts. The SDK needs raw productivity UI: property grids with dozens of fields, type-ahead search in entity palettes, nested tree views for trigger folders, side-by-side diff panels. egui provides all of these out of the box. bevy_egui is a mature integration crate. The game never shows egui (it uses themed bevy_ui); the SDK uses both.

Why ic-render for the viewport: The editor viewport must show exactly what the game will show — same sprite draw modes, same z-ordering, same palette application, same shroud rendering. If the editor used a simplified renderer, creators would encounter “looks different in-game” surprises. Reusing ic-render eliminates this class of bugs entirely.

What Graphical Resources the Editor Uses

The SDK does not need its own art assets for the editor chrome — it uses egui’s default styling (suitable for professional tools) plus the game’s own assets for content preview.

Key point: The SDK ships with minimal original art — just icons and cursors for the editor UI itself. All game content (sprites, terrain, palettes, audio) comes from the player’s installed games. This is the same legal model as the game: IC never distributes copyrighted assets.

Entity palette thumbnails: When the SDK loads a game module, it renders a small thumbnail for every placeable entity type — a 48×48 preview showing the unit’s idle frame. These are cached on disk after first generation. The entity palette (left panel in Entities mode) displays these as a searchable grid, with categories, favorites, and recently-placed lists. This is the “Garry’s Mod spawn menu” UX described in D038 — search-as-you-type finds any entity instantly.

UX Flow — How a Creator Uses the Editor

Creating a New Scenario (5-minute orientation)

1. Launch SDK. Opens to a start screen: New Scenario, Open Scenario, Open Campaign, Asset Studio, Recent Files.
2. New Scenario. Dialog: choose map size, theater (Temperate/Snow/Interior), game module (RA1/TD/custom mod). A blank map with terrain generates.
3. Terrain mode (default). Terrain brush active. Paint terrain tiles by clicking and dragging. Brush sizes 1×1 to 7×7. Elevation tools if the game module supports Z. Right-click to eyedrop a tile type.
4. Switch to Entities mode (Tab or click). Entity palette appears in the left panel. Search for “Medium Tank” → click to select → click on map to place. Properties panel on the right shows the entity’s attributes: faction, facing, stance, health, veterancy, Probability of Presence, inline script.
5. Switch to Triggers mode. Draw a trigger area on the map. Set condition: “Any unit of Faction A enters this area.” Set action: “Reinforcements module activates” (select a preconfigured module). Set countdown timer with min/mid/max randomization.
6. Switch to Modules mode. Browse built-in modules (Wave Spawner, Patrol Route, Reinforcements, Objectives). Drag a module onto the map or assign it to a trigger.
7. Press Test. SDK launches ic-game with this scenario via LocalNetwork. Play the mission. Close game → return to editor. Iterate.
8. Press Publish. Exports as .oramap-compatible package → uploads to Workshop (D030).

Simple ↔ Advanced Mode

D038 defines a Simple/Advanced toggle controlling which features are visible:

Simple mode hides 15+ features to present a clean, approachable interface. A new creator sees: terrain tools, entity palette, basic triggers, pre-built modules, waypoints, and a Test button. That’s enough to build a complete mission. Advanced mode reveals the full power. Toggle at any time — no data loss.

Editor Viewport — What Gets Rendered

The viewport is not just a map — it renders multiple overlay layers on top of the game’s normal isometric view:

Layer 0:   Terrain tiles (from ic-render, same as game)
Layer 1:   Grid overlay (faint lines showing cell boundaries, toggle-able)
Layer 2:   Region highlights (named regions shown as colored overlays)
Layer 3:   Trigger areas (pulsing colored boundaries with labels)
Layer 4:   Entities (buildings, units — rendered via ic-render)
Layer 5:   Waypoint markers (numbered circles with directional arrows)
Layer 6:   Connection lines (links between triggers, modules, waypoints)
Layer 7:   Entity selection highlight (selected entity's bounding box)
Layer 8:   Placement ghost (translucent preview of entity being placed)
Layer 9:   Cursor tool overlay (brush circle for terrain, snap indicator)

Layers 1–3 and 5–9 are editor-only overlays drawn on top of the game rendering. They use basic 2D shapes (rectangles, circles, lines, text labels) rendered via Bevy’s Gizmos system or a simple overlay pass. No complex art assets needed — colored geometric primitives with alpha transparency.

Asset Studio GUI

The Asset Studio is a tab within the same SDK application. Its layout differs from the scenario editor:

┌───────────────────────────────────────────────────────────────────────┐
│  IC SDK  — Asset Studio                                               │
├───────────────────────┬───────────────────────────┬───────────────────┤
│                       │                           │                   │
│  ASSET BROWSER        │    PREVIEW VIEWPORT       │  PROPERTIES       │
│                       │                           │                   │
│  📁 conquer.mix       │   (sprite viewer with     │  Frames: 52       │
│    ├── e1.shp         │    palette applied,        │  Width: 50        │
│    ├── 1tnk.shp       │    animation controls,     │  Height: 39       │
│    └── ...            │    zoom, frame scrub)      │  Draw mode:       │
│  📁 temperat.mix      │                           │    [Normal ▾]     │
│    └── ...            │   ◄ ▶ ⏸ ⏮ ⏭  Frame 12/52 │  Palette:         │
│  📁 local assets      │                           │    [temperat ▾]   │
│    └── my_sprite.png  │                           │  Player color:    │
│                       │                           │    [Red ▾]        │
│  🔎 Search...         │                           │                   │
├───────────────────────┴───────────────────────────┼───────────────────┤
│  TOOLS:  [Import] [Export] [Batch] [Compare]      │  In-context:      │
│                                                    │  [Preview as unit]│
└────────────────────────────────────────────────────┴───────────────────┘

Three columns: Asset browser (tree view of loaded archives + local files), preview viewport (sprite/palette/audio/video viewer), and properties panel (metadata + editing controls). The bottom row has action buttons and the “preview as unit / building / chrome” in-context buttons that render the asset on an actual map tile (using ic-render).

How to Start Building the Editor

The editor bootstraps on top of the game’s rendering — so the first-runnable (§ “First Runnable” above) is a prerequisite. Once the engine can load and render RA maps, the editor development follows a clear sequence:

Phase 6a Bootstrapping (Editor MVP)

Total: ~18 weeks for a functional scenario editor MVP. This covers the “core scenario editor” deliverable from Phase 6a — everything a creator needs to build and publish a playable mission.

Asset Studio Bootstrapping

The Asset Studio can be developed in parallel once ra-formats is mature (Phase 0):

Total: ~10 weeks for Asset Studio Layer 1 (browser/viewer) + Layer 2 (basic editing). Layer 3 (LLM generation) is Phase 7.

Do We Have Enough Information?

Yes — the design is detailed enough to build from. The critical path is clear:

1. Rendering engine (§ “First Runnable”) is the prerequisite. Without ra-formats and ic-render, there’s no viewport.
2. GUI framework (egui) is a known, mature Rust crate. No research needed — it has property inspectors, tree views, text editors, and all the widget types the SDK needs.
3. Viewport rendering reuses ic-render — the same code that renders the game renders the editor viewport. This eliminates the hardest rendering problem.
4. Editor overlays (trigger zones, waypoints, grid lines) are simple 2D shapes on top of the game render. Bevy’s Gizmos API handles this.
5. Data model is defined — scenarios are YAML + map.bin (OpenRA-compatible format), triggers are YAML structs, modules are YAML + Lua. No new format to invent.
6. Feature scope is defined in D038 (every module, every trigger type, every panel). The question is NOT “what should the editor do” — that’s answered. The question is “in what order do we build it” — and that’s answered by the phasing table above.

What remains open:

• P003 (audio library choice) affects the Asset Studio’s audio player but not the scenario editor
• Exact egui widget customization for the entity palette (search UX, thumbnail rendering) needs prototyping
• Campaign graph editor’s visual layout algorithm (auto-layout for mission nodes) needs implementation experimentation
• The precise line between bevy_ui and egui usage may shift during development — start with egui for everything, migrate specific widgets to bevy_ui only if styling needs demand it

See decisions/09f/D038-scenario-editor.md for the full scenario editor feature catalog, and decisions/09f/D040-asset-studio.md for the Asset Studio’s three-layer architecture and format support tables.

Multi-Game Extensibility (Game Modules)

Multi-Game Extensibility (Game Modules)

The engine is designed as a game-agnostic RTS framework (D039) that ships with Red Alert (default) and Tiberian Dawn as built-in game modules. The same engine can run RA2, Dune 2000, or an original game as additional game modules — like OpenRA runs TD, RA, and D2K on one engine.

Game Module Concept

A game module is a bundle of:

#![allow(unused)]
fn main() {
/// Each supported game implements this trait.
pub trait GameModule {
    /// Register ECS components (unit types, mechanics) into the world.
    fn register_components(&self, world: &mut World);

    /// Return the ordered system pipeline for this game's simulation tick.
    fn system_pipeline(&self) -> Vec<Box<dyn System>>;

    /// Provide the pathfinding implementation (selected by lobby/experience profile, D045).
    fn pathfinder(&self) -> Box<dyn Pathfinder>;

    /// Provide the spatial index implementation (spatial hash, BVH, etc.).
    fn spatial_index(&self) -> Box<dyn SpatialIndex>;

    /// Provide the fog of war implementation (radius, elevation LOS, etc.).
    fn fog_provider(&self) -> Box<dyn FogProvider>;

    /// Provide the damage resolution algorithm (standard, shield-first, etc.).
    fn damage_resolver(&self) -> Box<dyn DamageResolver>;

    /// Provide order validation logic (D041 — engine enforces this before apply_orders).
    fn order_validator(&self) -> Box<dyn OrderValidator>;

    /// Register format loaders (e.g., .vxl for RA2, .shp for RA1).
    fn register_format_loaders(&self, registry: &mut FormatRegistry);

    /// Register render backends (sprite renderer, voxel renderer, etc.).
    fn register_renderers(&self, registry: &mut RenderRegistry);

    /// List available render modes — Classic, HD, 3D, etc. (D048).
    fn render_modes(&self) -> Vec<RenderMode>;

    /// Register game-module-specific commands into the Brigadier command tree (D058).
    /// RA1 registers `/sell`, `/deploy`, `/stance`, etc. A total conversion registers
    /// its own novel commands. The engine's built-in commands (chat, help, cvars) are
    /// pre-registered before this method is called.
    fn register_commands(&self, dispatcher: &mut CommandDispatcher);

    /// YAML rule schema for this game's unit definitions.
    fn rule_schema(&self) -> RuleSchema;
}
}

Validation from OpenRA mod ecosystem: Analysis of six major OpenRA community mods (see research/openra-mod-architecture-analysis.md) confirms that every GameModule trait method addresses a real extension need:

• register_format_loaders() — OpenKrush (KKnD on OpenRA) required 15+ custom binary format decoders (.blit, .mobd, .mapd, .lvl, .son, .vbc) that bear no resemblance to C&C formats. TiberianDawnHD needed RemasterSpriteSequence for 128×128 HD tiles. Format extensibility is not optional for non-C&C games.
• system_pipeline() — OpenKrush replaced 16 complete mechanic modules (construction, production, oil economy, researching, bunkers, saboteurs, veterancy). OpenSA (Swarm Assault) added living-world systems (plant growth, creep spawners, colony capture). The pipeline cannot be fixed.
• render_modes() — TiberianDawnHD is a pure render-only mod (zero gameplay changes) that adds HD sprite rendering with content source detection (Steam AppId, Origin registry, GOG paths). Render mode extensibility enables this cleanly.
• pathfinder() — OpenSA needed WaspLocomotor (flying insect pathfinding); OpenRA/ra2 defines 8 locomotor types (Hover, Mech, Jumpjet, Teleport, etc). RA1’s JPS + flowfield is not universal.
• fog_provider() / damage_resolver() — RA2 needs elevation-based LOS and shield-first damage; OpenHV needs a completely different resource flow model (Collector → Transporter → Receiver pipeline). Game-specific logic belongs in the module.
• register_commands() — RA1 registers /sell, /deploy, /stance, superweapon commands. A Tiberian Dawn module registers different superweapon commands. A total conversion registers entirely novel commands. The engine cannot predefine game-specific commands (D058).

What the engine provides (game-agnostic)

RA2 Extension Points

RA2 / Tiberian Sun would add these to the existing engine without modifying the core:

Current Target: The Isometric C&C Family

The first-party game modules target the isometric C&C family: Red Alert, Red Alert 2, Tiberian Sun, Tiberian Dawn, and Dune 2000 (plus expansions and total conversions in the same visual paradigm). These games share:

• Fixed isometric camera
• Grid-based terrain (with optional elevation for TS/RA2)
• Sprite and/or voxel-to-sprite rendering
• .mix archives and related format lineage
• Discrete cell-based pathfinding (flowfields, hierarchical A*)

Architectural Openness: Beyond Isometric

C&C Generals and later 3D titles (C&C3, RA3) are not current targets — we build only grid-based pathfinding and isometric rendering today. But the architecture deliberately avoids closing doors:

The key insight: the engine core (Simulation, apply_tick(), GameLoop, NetworkModel, Pathfinder, SpatialIndex, FogProvider, DamageResolver, OrderValidator) is spatial-model-agnostic. Grid-based pathfinding is a game module implementation, not an engine assumption — the same way LocalNetwork is a network implementation, not the only possible one.

A Generals-class game module would provide its own Pathfinder (navmesh), SpatialIndex (BVH), FogProvider (elevation LOS), DamageResolver (sub-object targeting), AiStrategy (custom AI), Renderable (mesh), and format loaders — while reusing the sim core, networking, modding infrastructure, workshop, competitive infrastructure, and all shared systems (production, veterancy, replays, save games). See D041 in decisions/09d-gameplay.md for the full trait-abstraction strategy.

This is not a current development target. We build only the grid implementations. But the trait seams exist from day one, so the door stays open — for us or for the community.

3D Rendering as a Mod (Not a Game Module)

While 3D C&C titles are not current development targets, the architecture explicitly supports 3D rendering mods for any game module. A “3D Red Alert” mod replaces the visual presentation while the simulation, networking, pathfinding, and rules are completely unchanged.

This works because the sim/render split is absolute — the sim has no concept of camera, sprites, or visual style. Bevy already ships a full 3D pipeline (PBR materials, GLTF loading, skeletal animation, dynamic lighting, shadows), so a 3D render mod leverages existing infrastructure.

What changes vs. what doesn’t:

Architectural requirements to enable this:

1. Renderable trait is mod-swappable. A WASM Tier 3 mod can register a 3D render backend that replaces the default sprite renderer.
2. Camera system is configurable. Default is fixed isometric; a 3D mod substitutes a free-rotating perspective camera. The camera is purely a render concern — the sim has no camera concept.
3. Asset pipeline accepts 3D models. Bevy natively loads GLTF/GLB. The mod maps unit IDs to 3D model paths in YAML:

# Classic 2D (default)
rifle_infantry:
  render:
    type: sprite
    sequences: e1

# 3D mod override
rifle_infantry:
  render:
    type: mesh
    model: models/infantry/rifle.glb
    animations:
      idle: Idle
      move: Run
      attack: Shoot

4. Click-to-world abstracted behind trait. Isometric screen→world is a linear transform. 3D perspective screen→world is a raycast. Both produce a WorldPos. Grid-based game modules convert to CellPos as needed.
5. Terrain rendering decoupled from terrain data. The sim’s spatial representation is authoritative. A 3D mod provides visual terrain geometry that matches it.

Key benefits:

• Cross-view multiplayer. A player running 3D can play against a player running classic isometric — the sim is identical. Like StarCraft Remastered’s graphics toggle, but more radical.
• Cross-view replays. Watch any replay in 2D or 3D.
• Orthogonal to gameplay mods. A balance mod works in both views. A 3D graphics mod stacks with a gameplay mod.
• Toggleable, not permanent. D048 (Switchable Render Modes) formalizes this: a 3D render mod adds a render mode alongside the default 2D modes. F1 cycles between classic, HD, and 3D — the player isn’t locked into one view. See decisions/09d/D048-render-modes.md.

This is a Tier 3 (WASM) mod — it replaces a rendering backend, which is too deep for YAML or Lua. See 04-MODDING.md for details.

Design Rules for Multi-Game Safety

1. No game-specific enums in engine core. Don’t put enum ResourceType { Ore, Gems } in ic-sim. Resource types come from YAML rules / game module registration.
2. Position is always 3D. WorldPos carries Z. RA1 sets it to 0. The cost is one extra i32 per position — negligible. CellPos is a grid-game-module convenience type, not an engine-core requirement.
3. Pathfinding and spatial queries are behind traits. Pathfinder and SpatialIndex — like NetworkModel. Grid implementations are the default; the engine core never calls grid-specific functions directly.
4. System pipeline is data, not code. The game module returns its system list; the engine executes it. No hardcoded harvester_system() call in engine core.
5. Render through Renderable trait. Sprites and voxels implement the same trait. The renderer doesn’t know what it’s drawing.
6. Format loaders are pluggable. ra-formats provides parsers; the game module tells the asset pipeline which ones to use.
7. PlayerOrder is extensible. Use an enum with a Custom(GameSpecificOrder) variant, or make orders generic over the game module.
8. Fog, damage, and validation are behind traits (D041). FogProvider, DamageResolver, and OrderValidator — each game module supplies its own implementation. The engine core calls trait methods, never game-specific fog/damage/validation logic directly.
9. AI strategy is behind a trait (D041). AiStrategy lets each game module (or difficulty preset) supply different decision-making logic. The engine schedules AI ticks; the strategy decides what to do.

Type-Safety Architectural Invariants

Type-Safety Architectural Invariants

The type system is the first line of defense against logic bugs. These rules are non-negotiable and enforced via clippy::disallowed_types, custom lints, and code review.

Newtype Policy: No Bare Integer IDs

Every domain identifier uses a newtype wrapper. Bare u32, u64, or usize values must never be used as entity IDs, player IDs, slot indices, or any other domain concept.

#![allow(unused)]
fn main() {
// CORRECT — newtypes prevent ID confusion at compile time
pub struct PlayerId(u32);
pub struct SlotIndex(u8);
pub struct AccountId(u64);
pub struct UnitId(Entity);     // wraps Bevy Entity
pub struct BuildingId(Entity);
pub struct ProjectileId(Entity);
pub struct SimTick(u64);

// WRONG — bare integers allow passing a PlayerId where a SlotIndex is expected
fn apply_order(player: u32, slot: u32, tick: u64) { ... }
}

Extended newtypes — the same policy applies to every domain identifier across all crates:

#![allow(unused)]
fn main() {
// Simulation timing — NEVER confuse SubTickTimestamp with SimTick.
// SimTick counts whole ticks. SubTickTimestamp is a microsecond offset
// within a single tick window, used for sub-tick order fairness (D008).
pub struct SubTickTimestamp(u32);

// Campaign system (D021)
pub struct MissionId(u32);
pub struct OutcomeName(CompactString);  // validated: ASCII alphanumeric + underscore only

// Balance / AI / UI systems
pub struct PresetId(u32);       // balance preset (D019)
pub struct ThemeId(u32);        // UI theme (D032)
pub struct PersonalityId(u32);  // AI personality (D043)

// Workshop / packaging (D030)
pub struct PublisherId(u64);
pub struct PackageName(CompactString);  // validated: [a-z0-9-], 3-64 chars
pub struct PackageVersion(u32, u32, u32);  // Major.Minor.Patch — no string parsing at runtime

// WASM sandbox
pub struct WasmInstanceId(u32);

// Cryptographic identity — private field prevents construction with wrong hash
pub struct Fingerprint([u8; 32]);
}

Fingerprint is constructible only via its compute function:

#![allow(unused)]
fn main() {
impl Fingerprint {
    /// Compute fingerprint from canonical byte representation.
    /// This is the ONLY way to create a Fingerprint.
    pub fn compute(data: &[u8]) -> Self {
        Self(sha256(data))
    }
    pub fn as_bytes(&self) -> &[u8; 32] { &self.0 }
}
}

VersionConstraint must be a parsed enum, not a string:

#![allow(unused)]
fn main() {
// CORRECT — parsed at ingestion; invalid syntax is a type error thereafter
pub enum VersionConstraint {
    Exact(PackageVersion),
    Compatible(PackageVersion),            // ^1.2.3 = >=1.2.3, <2.0.0
    Range { min: PackageVersion, max: PackageVersion },
    GreaterOrEqual(PackageVersion),
}

// WRONG — string re-parsed everywhere; can silently contain invalid syntax
pub type VersionConstraint = String;
}

Rationale: The audit identified PlayerId ↔ SlotIndex ↔ AccountId confusion as a critical bug class. A function accepting (u32, u32, u64) has no compile-time protection against argument swaps. Newtypes make this a type error. The extended set applies the same principle to timing (sub-tick vs tick), identity (fingerprints), content (versions, packages), and campaign structure (missions, outcomes).

Enforcement: clippy::disallowed_types bans u32 and u64 in function signatures within ic-sim (exceptions via #[allow] with justification comment). See 16-CODING-STANDARDS.md § “Type-Safety Coding Standards” for the full clippy configuration and code review checklists covering all newtypes listed here.

Fixed-Point Math Policy: No f32/f64 in ic-sim

This is the project’s most fundamental type-safety invariant (Invariant #1). All game logic in ic-sim uses fixed-point math (i32/i64 with known scale). IEEE 754 floats are banned from the simulation because they produce platform-dependent results (x87 vs SSE, FMA contraction, different rounding modes), making deterministic cross-platform replay impossible.

#![allow(unused)]
fn main() {
// CORRECT — fixed-point with known scale (e.g., 1024 = 1.0)
pub struct FixedPoint(i32);

// WRONG — float non-determinism breaks cross-platform replay
fn move_unit(pos: &mut f32, speed: f32) { *pos += speed; }
}

Scope: f32 and f64 are banned in ic-sim only. They are permitted in:

• ic-game / ic-audio — rendering, interpolation, audio volume (presentation-only)
• ic-ui — UI layout, display values, diagnostic overlays
• Server-side infrastructure — matchmaking ratings, telemetry aggregation

Enforcement: clippy::disallowed_types bans f32 and f64 in the ic-sim crate. CI blocks on violations. Exceptions require #[allow] with a justification comment explaining why the float does not affect determinism.

Rationale: The Source SDK 2013 study (research/source-sdk-2013-source-study.md) documents Source Engine’s runtime IS_NAN() checks and bit-level float comparison (NetworkParanoidUnequal) as evidence that float-based determinism is fundamentally unreliable. IC eliminates this class of bug entirely.

Deterministic Collection Policy: No HashSet/HashMap in ic-sim

std::collections::HashSet and std::collections::HashMap use randomized hashing (RandomState). Iteration order varies between runs, breaking determinism (Invariant #1).

#![allow(unused)]
fn main() {
// CORRECT — deterministic alternatives
use std::collections::BTreeSet;
use std::collections::BTreeMap;
use indexmap::IndexMap;  // insertion-order deterministic

// WRONG — non-deterministic iteration order
use std::collections::HashSet;
use std::collections::HashMap;
}

Exceptions:

• ic-game (render-side) may use HashMap/HashSet where iteration order doesn’t affect sim state
• ic-net may use HashMap for connection lookup tables (not replicated to sim)
• ic-sim may use HashSet/HashMap only for membership tests where the set is never iterated (requires #[allow] with justification)

Enforcement: clippy::disallowed_types in ic-sim crate’s clippy.toml. CI blocks on violations.

Typestate Policy: State Machines Use Types, Not Enums

Any system with distinct states and restricted transitions must use the typestate pattern. Runtime enum matching for state transitions is a bug waiting to happen.

#![allow(unused)]
fn main() {
// CORRECT — typestate enforces valid transitions at compile time
pub struct Connection<S: ConnectionState> {
    inner: ConnectionInner,
    _state: PhantomData<S>,
}

pub struct Disconnected;
pub struct Handshaking;
pub struct Authenticated;
pub struct InGame;

impl Connection<Disconnected> {
    pub fn begin_handshake(self) -> Connection<Handshaking> { ... }
}
impl Connection<Handshaking> {
    pub fn authenticate(self, cred: &Credential) -> Result<Connection<Authenticated>, AuthError> { ... }
}
impl Connection<Authenticated> {
    pub fn join_game(self, lobby: LobbyId) -> Connection<InGame> { ... }
}

// WRONG — runtime enum allows invalid transitions
pub enum ConnectionState { Disconnected, Handshaking, Authenticated, InGame }
impl Connection {
    pub fn transition(&mut self, to: ConnectionState) { self.state = to; } // any transition allowed!
}
}

Applies to: Connection lifecycle, lobby state machine, game phase transitions, install wizard steps, Workshop package lifecycle, mod loading pipeline, and the following subsystem-specific lifecycles:

WASM Instance Lifecycle (D005):

#![allow(unused)]
fn main() {
pub struct WasmLoading;
pub struct WasmReady;
pub struct WasmExecuting;
pub struct WasmTerminated;

pub struct WasmSandbox<S> {
    instance_id: WasmInstanceId,
    inner: WasmInstanceInner,
    _state: PhantomData<S>,
}

impl WasmSandbox<WasmLoading> {
    pub fn initialize(self) -> Result<WasmSandbox<WasmReady>, WasmLoadError> { ... }
}
impl WasmSandbox<WasmReady> {
    pub fn execute(self, entry: &str) -> WasmSandbox<WasmExecuting> { ... }
}
impl WasmSandbox<WasmExecuting> {
    pub fn complete(self) -> WasmSandbox<WasmTerminated> { ... }
}
// Cannot call execute() on WasmTerminated — it's a compile error.
}

Workshop Package Install Lifecycle (D030):

#![allow(unused)]
fn main() {
pub struct PkgQueued;
pub struct PkgDownloading;
pub struct PkgVerifying;
pub struct PkgExtracted;

pub struct PackageInstall<S> {
    manifest: PackageManifest,
    _state: PhantomData<S>,
}

impl PackageInstall<PkgDownloading> {
    pub fn verify(self) -> Result<PackageInstall<PkgVerifying>, IntegrityError> { ... }
}
impl PackageInstall<PkgVerifying> {
    pub fn extract(self) -> Result<PackageInstall<PkgExtracted>, ExtractionError> { ... }
}
// Cannot call extract() on PkgDownloading — hash must be verified first.
}

Campaign Mission Execution (D021):

#![allow(unused)]
fn main() {
pub struct MissionLoading;
pub struct MissionActive;
pub struct MissionCompleted;
pub struct MissionTransitioned;

pub struct MissionExecution<S> {
    mission_id: MissionId,
    _state: PhantomData<S>,
}

impl MissionExecution<MissionActive> {
    pub fn complete(self, outcome: OutcomeName) -> MissionExecution<MissionCompleted> { ... }
}
impl MissionExecution<MissionCompleted> {
    pub fn transition(self) -> MissionExecution<MissionTransitioned> { ... }
}
// Cannot complete a mission that is still loading.
}

Balance Patch Application (D019):

#![allow(unused)]
fn main() {
pub struct PatchPending;
pub struct PatchValidated;
pub struct PatchApplied;

pub struct BalancePatch<S> {
    preset_id: PresetId,
    _state: PhantomData<S>,
}

impl BalancePatch<PatchPending> {
    pub fn validate(self) -> Result<BalancePatch<PatchValidated>, PresetError> { ... }
}
impl BalancePatch<PatchValidated> {
    pub fn apply(self) -> BalancePatch<PatchApplied> { ... }
}
// Cannot apply an unvalidated patch.
}

Capability Token Policy: Mod Sandbox Uses Unforgeable Tokens

WASM and Lua mods access engine APIs through capability tokens — unforgeable proof-of-authorization values that the host creates and the mod cannot construct.

#![allow(unused)]
fn main() {
/// Capability token for filesystem read access. Only the host can create this.
pub struct FsReadCapability {
    allowed_path: StrictPath<PathBoundary>,
    _private: (),  // prevents construction outside this module
}

/// Mod API: read a file (requires capability token)
pub fn read_file(cap: &FsReadCapability, relative: &str) -> Result<Vec<u8>, SandboxError> {
    let full = cap.allowed_path.join(relative)?; // strict-path enforces boundary
    std::fs::read(full.as_ref()).map_err(SandboxError::Io)
}
}

Rationale: Without capability tokens, a compromised or malicious mod can call any host function. With tokens, the host controls exactly what each mod can access. Token types are zero-sized at runtime — no overhead.

Direction-Branded Messages: Network Message Origin

Messages from the client and messages from the server must be distinct types, even if they carry the same payload. This prevents a client-originated message from being mistaken for a server-authoritative message.

#![allow(unused)]
fn main() {
pub struct FromClient<T>(pub T);
pub struct FromServer<T>(pub T);

// Server code accepts only FromClient messages
fn handle_order(msg: FromClient<PlayerOrder>) { ... }

// Client code accepts only FromServer messages
fn handle_state_update(msg: FromServer<SimSnapshot>) { ... }
}

Bounded Collections: No Unbounded Growth in Sim State

Any collection in ic-sim that grows based on player input must have a compile-time or construction-time bound. Unbounded collections are a denial-of-service vector.

#![allow(unused)]
fn main() {
pub struct BoundedVec<T, const N: usize> {
    inner: Vec<T>,
}

impl<T, const N: usize> BoundedVec<T, N> {
    pub fn push(&mut self, item: T) -> Result<(), CapacityExceeded> {
        if self.inner.len() >= N {
            return Err(CapacityExceeded);
        }
        self.inner.push(item);
        Ok(())
    }
}
}

Applies to: Order queues, chat message buffers, marker lists, waypoint sequences, build queues, group assignments.

Hash Type Distinction: SyncHash vs StateHash

The netcode uses two different hash widths for different purposes. Using the wrong one silently produces incorrect verification results.

#![allow(unused)]
fn main() {
/// Fast sync hash: 64-bit truncation for per-tick live comparison.
/// Used in the desync detection hot path (every sync frame).
pub struct SyncHash(u64);

/// Full state hash: SHA-256 for replay signing, snapshot verification,
/// and Merkle tree leaves. Used in cold paths (save, replay, debug).
pub struct StateHash([u8; 32]);
}

Rationale: The netcode defines a “fast sync hash” (u64) for per-tick RNG comparison and a “full SHA-256” for Merkle tree leaves and replay signing (see 03-NETCODE.md). A bare u64 where [u8; 32] was expected (or vice versa) silently produces incorrect verification. Distinct types prevent confusion.

Enforcement: No implicit conversion between SyncHash and StateHash. Truncation or expansion requires an explicit, named function.

Verified Wrapper Policy: Post-Verification Data

Many security bugs stem from processing data that was “supposed to” have been verified but was not. The Verified<T> wrapper makes verification status visible in the type system.

#![allow(unused)]
fn main() {
/// Wrapper that proves data has passed a specific verification step.
/// Cannot be constructed without going through the verification function.
pub struct Verified<T> {
    inner: T,
    _private: (),
}

impl<T> Verified<T> {
    /// Only verification functions should call this.
    pub(crate) fn new_verified(inner: T) -> Self {
        Self { inner, _private: () }
    }
    pub fn inner(&self) -> &T { &self.inner }
    pub fn into_inner(self) -> T { self.inner }
}
}

Applies to:

• Verified<SignedCredentialRecord> — an SCR whose Ed25519 signature has been checked (D052)
• Verified<ManifestHash> — a Workshop manifest whose content hash matches the declared hash (D030)
• Verified<ReplaySignature> — a replay whose signature chain has been validated
• ValidatedOrder (type alias for Verified<PlayerOrder>) — an order that passed all validation checks (D012)

Rationale: A function accepting Verified<SignedCredentialRecord> cannot receive an unverified SCR without a compile error. The new_verified constructor is pub(crate) to prevent external construction — only the actual verification function in the same crate can wrap a value.

Enforcement: Functions in ic-sim that consume verified data must accept Verified<T>, not bare T. Code review must check that new_verified() is called only inside actual verification logic (see 16-CODING-STANDARDS.md § “Verified Wrapper Review”).

Bounded Cvar Policy: Console Variables with Type-Enforced Ranges

The console variable system (D058) allows runtime configuration within defined ranges. Without type enforcement, any code path that sets a cvar can bypass the range check.

#![allow(unused)]
fn main() {
/// A console variable with compile-time or construction-time bounds.
/// Setting a value outside bounds clamps to the nearest bound.
pub struct BoundedCvar<T: Ord + Copy> {
    value: T,
    min: T,
    max: T,
    _private: (),
}

impl<T: Ord + Copy> BoundedCvar<T> {
    pub fn new(default: T, min: T, max: T) -> Self {
        let clamped = default.max(min).min(max);
        Self { value: clamped, min, max, _private: () }
    }
    pub fn set(&mut self, value: T) {
        self.value = value.max(self.min).min(self.max);
    }
    pub fn get(&self) -> T { self.value }
}
}

Rationale: BoundedCvar makes out-of-range values unrepresentable after construction. All cvars with documented valid ranges (e.g., net.simulate_latency 0–500ms, net.desync_debug_level 0–2) must use this type.

Chat Message Scope Branding

In RTS games, team chat vs all-chat is security-critical. A team message accidentally broadcast to all players leaks strategic information.

#![allow(unused)]
fn main() {
/// Chat scope marker types (zero-sized).
pub struct TeamScope;
pub struct AllScope;
pub struct WhisperScope;

/// A chat message branded with its delivery scope.
pub struct ChatMessage<S> {
    pub sender: PlayerId,
    pub text: SanitizedString,
    _scope: PhantomData<S>,
}

// Team chat handler accepts ONLY team messages
fn handle_team_chat(msg: ChatMessage<TeamScope>) { ... }

// All-chat handler accepts ONLY all-chat messages
fn handle_all_chat(msg: ChatMessage<AllScope>) { ... }
}

Rationale: Branding the message type with its scope makes routing errors a compile-time type mismatch. Conversion between scopes requires an explicit, auditable function call. This extends the direction-branded messages pattern (see FromClient<T> / FromServer<T> above) to chat delivery scope.

Validated Construction Policy: Invariant-Checked Types

Some types have invariants that cannot be encoded in const generics but must hold for correctness. The “validated construction” pattern puts the check at the only place values are created, making invalid instances unconstructible.

#![allow(unused)]
fn main() {
/// A campaign graph that has been validated as a DAG at construction time.
/// Cannot be constructed without passing validation.
pub struct CampaignGraph {
    missions: BTreeMap<MissionId, MissionDef>,
    edges: Vec<(MissionId, OutcomeName, MissionId)>,
    _private: (),  // prevents construction outside this module
}

impl CampaignGraph {
    /// Validate and construct. Returns error if graph contains cycles,
    /// unreachable missions, or dangling outcome references.
    pub fn new(
        missions: BTreeMap<MissionId, MissionDef>,
        edges: Vec<(MissionId, OutcomeName, MissionId)>,
    ) -> Result<Self, CampaignGraphError> {
        Self::validate_dag(&missions, &edges)?;
        Self::validate_reachability(&missions, &edges)?;
        Self::validate_references(&missions, &edges)?;
        Ok(Self { missions, edges, _private: () })
    }
}
}

#![allow(unused)]
fn main() {
/// An order budget with valid invariants (tokens <= burst_cap, refill > 0).
pub struct OrderBudget {
    tokens: u32,
    refill_per_tick: u32,
    burst_cap: u32,
    _private: (),
}

impl OrderBudget {
    pub fn new(refill_per_tick: u32, burst_cap: u32) -> Result<Self, InvalidBudget> {
        if refill_per_tick == 0 || burst_cap == 0 {
            return Err(InvalidBudget);
        }
        Ok(Self { tokens: burst_cap, refill_per_tick, burst_cap, _private: () })
    }

    pub fn try_spend(&mut self) -> Result<(), BudgetExhausted> {
        if self.tokens == 0 { return Err(BudgetExhausted); }
        self.tokens -= 1;
        Ok(())
    }

    pub fn refill(&mut self) {
        self.tokens = (self.tokens + self.refill_per_tick).min(self.burst_cap);
    }
}
}

Rationale: CampaignGraph guarantees DAG structure, full reachability, and valid references at construction time — no downstream code needs to re-validate. OrderBudget guarantees tokens <= burst_cap and refill > 0 — the rate limiter cannot be constructed in a broken state.

Applies to: CampaignGraph, OrderBudget, BalancePreset (no circular inheritance), WeatherSchedule (non-empty cycle list, valid intensity ranges), DependencyGraph (no cycles, all references resolve).

03 — Network Architecture

Our Netcode

Iron Curtain ships one default gameplay netcode today: relay-assisted deterministic lockstep with sub-tick order fairness. This is the recommended production path, not a buffet of equal options in the normal player UX. The NetworkModel trait still exists for more than testing: it lets us run single-player and replay modes cleanly, support multiple deployments (dedicated relay / embedded relay / P2P LAN), and preserve the ability to introduce deferred compatibility bridges or replace the default netcode under explicitly deferred milestones (for example M7+ interop experiments or M11 optional architecture work) if evidence warrants it (e.g., cross-engine interop experiments, architectural flaws discovered in production). Those paths require explicit decision/tracker placement and are not part of M4 exit criteria.

Keywords: netcode, relay lockstep, NetworkModel, sub-tick timestamps, reconnection, desync debugging, replay determinism, compatibility bridge, ranked authority, relay server

Key influences:

• Counter-Strike 2 — sub-tick timestamps for order fairness
• C&C Generals/Zero Hour — adaptive run-ahead, frame resilience, delta-compressed wire format, disconnect handling
• Valve GameNetworkingSockets (GNS) — ack vector reliability, message lanes with priority/weight, per-ack RTT measurement, pluggable signaling, transport encryption, Nagle-style batching (see research/valve-github-analysis.md)
• OpenTTD — multi-level desync debugging, token-based liveness, reconnection via state transfer
• Minetest — time-budget rate control (LagPool), half-open connection defense
• OpenRA — what to avoid: TCP stalling, static order latency, shallow sync buffers
• Bryant & Saiedian (2021) — state saturation taxonomy, traffic class segregation

The Protocol

All protocol types live in the ic-protocol crate — the ONLY shared dependency between sim and net:

#![allow(unused)]
fn main() {
#[derive(Clone, Serialize, Deserialize, Hash)]
pub enum PlayerOrder {
    Move { unit_ids: Vec<UnitId>, target: WorldPos },
    Attack { unit_ids: Vec<UnitId>, target: Target },
    Build { structure: StructureType, position: WorldPos },
    SetRallyPoint { building: BuildingId, position: WorldPos },
    Sell { building: BuildingId },
    Idle,  // Explicit no-op — keeps player in the tick's order list for timing/presence
    // ... every possible player action
}

/// Sub-tick timestamp on every order (CS2-inspired, see below).
/// In relay modes this is a client-submitted timing hint that the relay
/// normalizes/clamps before broadcasting canonical TickOrders.
#[derive(Clone, Serialize, Deserialize)]
pub struct TimestampedOrder {
    pub player: PlayerId,
    pub order: PlayerOrder,
    pub sub_tick_time: u32,  // microseconds within the tick window (0 = tick start)
}
// NOTE: sub_tick_time is an integer (microseconds offset from tick start).
// At 15 ticks/sec the tick window is ~66,667µs — u32 is more than sufficient.
// Integer ordering avoids any platform-dependent float comparison behavior
// and keeps ic-protocol free of floating-point types entirely.

pub struct TickOrders {
    pub tick: u64,
    pub orders: Vec<TimestampedOrder>,
}

impl TickOrders {
    /// CS2-style: process in chronological order within the tick.
    /// Uses a caller-provided scratch buffer to avoid per-tick heap allocation.
    /// The buffer is cleared and reused each tick (see TickScratch pattern in 10-PERFORMANCE.md).
    /// Tie-break by player ID so equal timestamps remain deterministic in P2P/LAN modes
    /// (relay modes may already emit canonical normalized timestamps, but the helper stays safe).
    pub fn chronological<'a>(&'a self, scratch: &'a mut Vec<&'a TimestampedOrder>) -> &'a [&'a TimestampedOrder] {
        scratch.clear();
        scratch.extend(self.orders.iter());
        scratch.sort_by_key(|o| (o.sub_tick_time, o.player));
        scratch.as_slice()
    }
}
}

How It Works

Architecture: Relay with Time Authority

The relay server is the recommended deployment for multiplayer. It does NOT run the sim — it’s a lightweight order router with time authority:

┌────────┐         ┌──────────────┐         ┌────────┐
│Player A│────────▶│ Relay Server │◀────────│Player B│
│        │◀────────│  (timestamped│────────▶│        │
└────────┘         │   ordering)  │         └────────┘
                   └──────────────┘

Every tick:

1. The relay receives timestamped orders from all players
2. Validates/normalizes client timestamp hints into canonical sub-tick timestamps (relay-owned timing calibration + skew bounds)
3. Orders them chronologically within the tick (CS2 insight — see below)
4. Broadcasts the canonical TickOrders to all clients
5. All clients run the identical deterministic sim on those orders

The relay also:

• Detects lag switches and cheating attempts (see anti-lag-switch below)
• Handles NAT traversal (no port forwarding needed)
• Signs replays for tamper-proofing (see 06-SECURITY.md)
• Validates order signatures and rate limits (see 06-SECURITY.md)

This design was validated by C&C Generals/Zero Hour’s “packet router” — a client-side star topology where one player collected and rebroadcast all commands. Same concept, but our server-hosted version eliminates host advantage and adds neutral time authority. See research/generals-zero-hour-netcode-analysis.md.

Further validated by Embark Studios’ Quilkin (1,510★, Apache 2.0, co-developed with Google Cloud Gaming) — a production UDP proxy for game servers built in Rust. Quilkin implements the relay as a composable filter chain: each packet passes through an ordered pipeline of filters (Capture → Firewall → RateLimit → TokenRouter → Timestamp → Debug), and filters can be added, removed, or reordered without touching routing logic. IC’s relay should adopt this composable architecture: order validation → sub-tick timestamps → replay recording → anti-cheat → forwarding, each implemented as an independent filter. See research/embark-studios-rust-gamedev-analysis.md § Quilkin.

For small games (2-3 players) on LAN or with direct connectivity, the same netcode runs without a relay via P2P lockstep (see “The NetworkModel Trait” section below for deployment modes).

RelayCore: Library, Not Just a Binary

The relay logic — order collection, sub-tick sorting, time authority, anti-lag-switch, token liveness — lives as a library component (RelayCore) inside ic-net, not only as a standalone server binary. This enables three deployment modes for the same relay functionality:

ic-net/
├── relay_core       ← The relay logic: order collection, sub-tick sorting,
│                       time authority, anti-lag-switch, token liveness,
│                       replay signing, composable filter chain
├── relay_server     ← Standalone binary wraps RelayCore (multi-game, headless)
└── embedded_relay   ← Game client wraps RelayCore (single game, host plays)

RelayCore is a pure-logic component — no I/O, no networking. It accepts incoming order packets, sorts them by sub-tick timestamp, produces canonical TickOrders, and runs the composable filter chain. The embedding layer (standalone binary or game client) handles actual network I/O and feeds packets into RelayCore.

#![allow(unused)]
fn main() {
/// The relay engine. Embedding-agnostic — works identically whether
/// hosted in a standalone binary or inside a game client.
pub struct RelayCore {
    tick: u64,
    pending_orders: Vec<TimestampedOrder>,
    filter_chain: Vec<Box<dyn RelayFilter>>,
    liveness_tokens: HashMap<PlayerId, LivenessToken>,
    clock_calibration: HashMap<PlayerId, ClockCalibration>,
    // ... anti-lag-switch state, replay signer, etc.
}

impl RelayCore {
    /// Feed an incoming order packet. Called by the network layer.
    pub fn receive_order(&mut self, player: PlayerId, order: TimestampedOrder) { ... }
    
    /// Produce the canonical TickOrders for this tick.
    /// Sub-tick sorts, runs filter chain, advances tick counter.
    pub fn finalize_tick(&mut self) -> TickOrders { ... }
    
    /// Generate liveness token for the next frame.
    pub fn next_liveness_token(&mut self, player: PlayerId) -> u32 { ... }
}
}

This creates three relay deployment modes:

Listen server vs. Generals’ star topology. C&C Generals used a star topology where the host player collected and rebroadcast orders — but the host had host advantage: zero self-latency, ability to peek at orders before broadcasting. With IC’s embedded RelayCore, the host’s own orders go through the same RelayCore pipeline as everyone else’s. Clients submit sub-tick timestamp hints from local clocks; the relay converts them into relay-canonical timestamps using the same normalization logic for every player. The host doesn’t get a privileged code path.

Trust boundary for ranked play. An embedded relay runs inside the host’s process — a malicious host could theoretically modify RelayCore behavior (drop opponents’ orders, manipulate timestamps). For ranked/competitive play, the matchmaking system requires connection to an official or community-verified relay server (standalone binary on trusted infrastructure). For casual, LAN, and custom games, the embedded relay is perfect — zero setup, “Host Game” button just works, no external server needed.

Connecting clients can’t tell the difference. Both the standalone binary and the embedded relay present the same protocol. RelayLockstepNetwork on the client side connects identically — it doesn’t know or care whether the relay is a dedicated server or running inside another player’s game client. This is a deployment concern, not a protocol concern.

Connection Lifecycle Type State

Network connections transition through a fixed lifecycle: Connecting → Authenticated → InLobby → InGame → Disconnecting. Calling the wrong method in the wrong state is a security risk — processing game orders from an unauthenticated connection, or sending lobby messages during gameplay, shouldn’t be possible to write accidentally.

IC uses Rust’s type state pattern to make invalid state transitions a compile error instead of a runtime bug:

#![allow(unused)]
fn main() {
use std::marker::PhantomData;

/// Marker types — zero-sized, exist only in the type system.
pub struct Connecting;
pub struct Authenticated;
pub struct InLobby;
pub struct InGame;

/// A network connection whose valid operations are determined by its state `S`.
/// `PhantomData<S>` is zero-sized — no runtime cost.
pub struct Connection<S> {
    stream: TcpStream,
    player_id: Option<PlayerId>,
    _state: PhantomData<S>,
}

impl Connection<Connecting> {
    /// Verify credentials. Consumes the Connecting connection,
    /// returns an Authenticated one. Can't be called twice.
    pub fn authenticate(self, cred: &Credential) -> Result<Connection<Authenticated>, AuthError> {
        // ... verify Ed25519 signature (D052), assign PlayerId
    }
    // send_order() doesn't exist here — won't compile.
}

impl Connection<Authenticated> {
    /// Join a game lobby. Consumes Authenticated, returns InLobby.
    pub fn join_lobby(self, room: RoomId) -> Result<Connection<InLobby>, LobbyError> {
        // ... register with lobby, send player list
    }
}

impl Connection<InLobby> {
    /// Transition to in-game when the lobby starts.
    pub fn start_game(self, game_id: GameId) -> Connection<InGame> {
        // ... initialize per-connection game state
    }

    pub fn send_chat(&self, msg: &ChatMessage) { /* ... */ }
    // send_order() doesn't exist here — won't compile.
}

impl Connection<InGame> {
    /// Submit a game order. Only available during gameplay.
    pub fn send_order(&self, order: &TimestampedOrder) { /* ... */ }

    /// Return to lobby after match ends.
    pub fn end_game(self) -> Connection<InLobby> {
        // ... cleanup per-connection game state
    }
}
}

Why this matters for IC:

• Security by construction. The relay server handles untrusted connections. A bug that processes game orders from a connection still in Connecting state is an exploitable vulnerability. Type state makes it a compile error — not a runtime check someone might forget.
• Zero runtime cost. PhantomData<S> is zero-sized. The state transitions compile to the same machine code as passing a struct between functions. No enum discriminant, no match statement, no branch prediction miss.
• Self-documenting API. The method signatures are the state machine documentation. If send_order() only exists on Connection<InGame>, no developer needs to check whether “Am I allowed to send orders here?” — the compiler already answered.
• Ownership-driven transitions. Each transition consumes the old connection and returns a new one. You can’t accidentally keep a reference to the Connecting version after authentication. Rust’s move semantics enforce this automatically.

Where NOT to use type state: Game entities. Units change state constantly at runtime (idle → moving → attacking → dead) driven by data-dependent conditions — that’s a runtime state machine (enum + match with exhaustiveness checking), not a compile-time type state. Type state is for state machines with a fixed, known-at-compile-time set of transitions — like connection lifecycle, file handles (open/closed), or build pipeline stages.

Sub-Tick Order Fairness (from CS2)

Counter-Strike 2 introduced “sub-tick” architecture: instead of processing all actions at discrete tick boundaries, the client timestamps every input with sub-tick precision. The server collects inputs from all clients and processes them in chronological order within each tick window. The server still ticks at 64Hz, but events are ordered by their actual timestamps.

For an RTS, the core idea — timestamped orders processed in chronological order within a tick — produces fairer results for edge cases:

• Two players grabbing the same crate → the one who clicked first gets it
• Engineer vs engineer racing to capture a building → chronological winner
• Simultaneous attack orders → processed in actual order, not arrival order

What’s NOT relevant from CS2: CS2 is client-server authoritative with prediction and interpolation. An RTS with hundreds of units can’t afford server-authoritative simulation — the bandwidth would be enormous. We stay with deterministic lockstep (clients run identical sims), so CS2’s prediction/reconciliation doesn’t apply.

Why Sub-Tick Instead of a Higher Tick Rate

In client-server FPS (CS2, Overwatch), a tick is just a simulation step — the server runs alone and sends corrections. In lockstep, a tick is a synchronization barrier: every tick requires collecting all players’ orders (or hitting the deadline), processing them deterministically, advancing the full ECS simulation, and exchanging sync hashes. Each tick is a coordination point between all players.

This means higher tick rates have multiplicative cost in lockstep:

At 128 tps, you’re running all pathfinding, spatial queries, combat resolution, fog updates, and economy for 500+ units 128 times per second instead of 30. That’s a 4× CPU increase with no gameplay benefit — RTS units move cell-to-cell, not sub-millimeter. Visual interpolation already makes 30 tps look smooth at 60+ FPS render.

Critically, 128 tps doesn’t even eliminate the problem sub-tick solves. Two orders landing in the same 8ms window still need a tiebreaker. You’ve paid 4× the cost and still need sub-tick logic (or unfair player-ID tiebreaking) for simultaneous orders.

Sub-tick decouples order fairness from simulation rate. That’s why it’s the right tool: it solves the fairness problem without paying the simulation cost. A tick’s purpose in lockstep is synchronization, and you want the fewest synchronization barriers that still produce good gameplay — not the most.

Relay-Side Timestamp Normalization (Trust Boundary)

The relay’s “time authority” guarantee is only meaningful if it does not blindly trust client-claimed sub-tick timestamps. Therefore:

• Client sub_tick_time is a hint, not an authoritative fact
• Relay assigns the canonical timestamp that is broadcast in TickOrders
• Impossible timestamps are clamped/flagged, not accepted as-is

The relay maintains a per-player timing calibration (offset/skew estimate + jitter envelope) derived from transport RTT samples and timing feedback. When an order arrives, the relay:

1. Determines the relay tick window the order belongs to (or drops it as late)
2. Computes a feasible arrival-time envelope for that player in that tick
3. Maps the client’s sub_tick_time hint into relay time using the calibration
4. Clamps to the feasible envelope and [0, tick_window_us) bounds
5. Emits the relay-normalized sub_tick_time in canonical TickOrders

Orders with repeated timestamp claims outside the allowed skew budget are treated as suspicious (telemetry + anti-abuse scoring; optional strike escalation in ranked relay deployments). This preserves the fairness benefit of sub-tick ordering while preventing “I clicked first” spoofing by client clock manipulation.

In P2P lockstep, there is no neutral time authority, so this normalization is not possible. P2P keeps the deterministic (sub_tick_time, player_id) ordering rule and explicitly accepts reduced fairness (acceptable for LAN/small-group play).

Adaptive Run-Ahead (from C&C Generals)

Every lockstep RTS has inherent input delay — the game schedules your order a few ticks into the future so remote players’ orders have time to arrive:

Local input at tick 50 → scheduled for tick 53 (3-tick delay)
Remote input has 3 ticks to arrive before we need it
Delay dynamically adjusted based on connection quality AND client performance

This input delay (“run-ahead”) is not static. It adapts dynamically based on both network latency and client frame rate — a pattern proven by C&C Generals/Zero Hour (see research/generals-zero-hour-netcode-analysis.md). Generals tracked a 200-sample rolling latency history plus a “packet arrival cushion” (how many frames early orders arrive) to decide when to adjust. Their run-ahead changes were themselves synchronized network commands, ensuring all clients switch on the same frame.

We adopt this pattern:

#![allow(unused)]
fn main() {
/// Sent periodically by each client to report its performance characteristics.
/// The relay server (or P2P host) uses this to adjust the tick deadline.
pub struct ClientMetrics {
    pub avg_latency_us: u32,      // Rolling average RTT to relay/host (microseconds)
    pub avg_fps: u16,             // Client's current rendering frame rate
    pub arrival_cushion: i16,     // How many ticks early orders typically arrive
    pub tick_processing_us: u32,  // How long the client takes to process one sim tick
}
}

Why FPS matters: a player running at 15 FPS needs roughly 67ms to process and display each frame. If run-ahead is only 2 ticks (66ms at 30 tps), they have zero margin — any network jitter causes a stall. By incorporating FPS into the adaptive algorithm, we prevent slow machines from dragging down the experience for everyone.

For the relay deployment, ClientMetrics informs the relay’s tick deadline calculation. For P2P lockstep, all clients agree on a shared run-ahead value (just like Generals’ synchronized RUNAHEAD command).

Input Timing Feedback (from DDNet)

The relay server periodically reports order arrival timing back to each client, enabling client-side self-calibration. This pattern is proven by DDNet’s timing feedback system (see research/veloren-hypersomnia-openbw-ddnet-netcode-analysis.md) where the server reports how early/late each player’s input arrived:

#![allow(unused)]
fn main() {
/// Sent by the relay to each client after every N ticks (default: 30).
/// Tells the client how its orders are arriving relative to the tick deadline.
pub struct TimingFeedback {
    pub avg_arrival_delta_us: i32,  // +N = arrived N μs before deadline, -N = late
    pub late_count: u16,            // orders missed deadline in this window
    pub jitter_us: u32,             // arrival time variance
}
}

The client uses this feedback to adjust when it submits orders — if orders are consistently arriving just barely before the deadline, the client shifts submission earlier. If orders are arriving far too early (wasting buffer), the client can relax. This is a feedback loop that converges toward optimal submission timing without the relay needing to adjust global tick deadlines, reducing the number of late drops for marginal connections.

Anti-Lag-Switch

The relay server owns the clock. If your orders don’t arrive within the tick deadline, they’re dropped — replaced with PlayerOrder::Idle. Lag switch only punishes the attacker:

#![allow(unused)]
fn main() {
impl RelayServer {
    fn process_tick(&mut self, tick: u64) {
        let deadline = Instant::now() + self.tick_deadline; // e.g., 120ms
        
        for player in &self.players {
            match self.receive_orders_from(player, deadline) {
                Ok(orders) => self.tick_orders.add(player, orders),
                Err(Timeout) => {
                    // Missed deadline → strikes system
                    // Game never stalls for honest players
                    self.tick_orders.add(player, PlayerOrder::Idle);
                }
            }
        }
        self.broadcast_tick_orders(tick);
    }
}
}

Repeated late deliveries accumulate strikes. Enough strikes → disconnection. The relay’s tick cadence is authoritative — client clock is irrelevant. See 06-SECURITY.md for the full anti-cheat implications.

Token-based liveness (from OpenTTD): The relay embeds a random nonce in each FRAME packet. The client must echo it in their ACK. This distinguishes “slow but actively processing” from “TCP-alive but frozen” — a client that maintains a connection without processing game frames (crashed renderer, debugger attached, frozen UI) is caught within one missed token, not just by eventual heartbeat timeout. The token check is separate from frame acknowledgment: legitimate lag (slow packets) delays the ACK but eventually echoes the correct token, while a frozen client never echoes.

Order Rate Control

Order throughput is controlled by three independent layers, each catching what the others miss:

Layer 1 — Time-budget pool (primary). Inspired by Minetest’s LagPool anti-cheat system. Each player has an order budget that refills at a fixed rate per tick and caps at a burst limit:

#![allow(unused)]
fn main() {
pub struct OrderBudget {
    pub tokens: u32,         // Current budget (each order costs 1 token)
    pub refill_per_tick: u32, // Tokens added per tick (e.g., 16 at 30 tps)
    pub burst_cap: u32,       // Maximum tokens (e.g., 128)
}

impl OrderBudget {
    fn tick(&mut self) {
        self.tokens = (self.tokens + self.refill_per_tick).min(self.burst_cap);
    }
    
    fn try_consume(&mut self, count: u32) -> u32 {
        let accepted = count.min(self.tokens);
        self.tokens -= accepted;
        accepted // excess orders silently dropped
    }
}
}

Why this is better than a flat cap: normal play (5-10 orders/tick) never touches the limit. Legitimate bursts (mass-select 50 units and move) consume from the burst budget and succeed. Sustained abuse (bot spamming hundreds of orders per second) exhausts the budget within a few ticks, and excess orders are silently dropped. During real network lag (no orders submitted), the budget refills naturally — when the player reconnects, they have a full burst budget for their queued commands.

Layer 2 — Bandwidth throttle. A token bucket rate limiter on raw bytes per client (from OpenTTD). bytes_per_tick adds tokens each tick, bytes_per_tick_burst caps the bucket. This catches oversized orders or rapid data that might pass the order-count budget but overwhelm bandwidth. Parameters are tuned so legitimate traffic never hits the limit.

Layer 3 — Hard ceiling. An absolute maximum of 256 orders per player per tick (defined in ProtocolLimits). This is the last resort — if somehow both budget and bandwidth checks fail, this hard cap prevents any single player from flooding the tick’s order list. See 06-SECURITY.md § Vulnerability 15 for the full ProtocolLimits definition.

Half-open connection defense (from Minetest): New UDP connections to the relay are marked half-open. The relay inhibits retransmission and ping responses until the client proves liveness by using its assigned session ID in a valid packet. This prevents the relay from being usable as a UDP amplification reflector — critical for any internet-facing server.

Relay connection limits: In addition to per-player order rate control, the relay enforces connection-level limits to prevent resource exhaustion (see 06-SECURITY.md § Vulnerability 24):

• Max total connections per relay instance: configurable, default 1000. Returns 503 when at capacity.
• Max connections per IP: configurable, default 5. Prevents single-source connection flooding.
• New connection rate per IP: max 10/sec (token bucket). Prevents rapid reconnection spam.
• Memory budget per connection: bounded; torn down if exceeded.
• Idle timeout: 60 seconds for unauthenticated, 5 minutes for authenticated.

These limits complement the order-level defenses — rate control handles abuse from established connections, connection limits prevent exhaustion of server resources before a game even starts.

Frame Data Resilience (from C&C Generals + Valve GNS)

UDP is unreliable — packets can arrive corrupted, duplicated, reordered, or not at all. Inspired by C&C Generals’ FrameDataManager (see research/generals-zero-hour-netcode-analysis.md), our frame data handling uses a three-state readiness model rather than a simple ready/waiting binary:

#![allow(unused)]
fn main() {
pub enum FrameReadiness {
    Ready,                     // All orders received and verified
    Waiting,                   // Still expecting orders from one or more players
    Corrupted { from: PlayerId }, // Orders received but failed integrity check — request resend
}
}

When Corrupted is detected, the system automatically requests retransmission from the specific player (or relay). A circular buffer retains the last N ticks of sent frame data (Generals used 65 frames) so resend requests can be fulfilled without re-generating the data.

This is strictly better than pure “missed deadline → Idle” fallback: a corrupted packet that arrives on time gets a second chance via resend rather than being silently replaced with no-op. The deadline-based Idle fallback remains as the last resort if resend also fails.

Ack Vector Reliability Model (from Valve GNS)

The reliability layer uses ack vectors — a compact bitmask encoding which of the last N packets were received — rather than TCP-style cumulative acknowledgment or selective ACK (SACK). This approach is borrowed from Valve’s GameNetworkingSockets (which in turn draws from DCCP, RFC 4340). See research/valve-github-analysis.md § Part 1.

How it works: Every outgoing packet includes an ack vector — a bitmask where each bit represents a recently received packet from the peer. Bit 0 = the most recently received packet (identified by its sequence number in the header), bit 1 = the one before that, etc. A 64-bit ack vector covers the last 64 packets. The sender inspects incoming ack vectors to determine which of its sent packets were received and which were lost.

#![allow(unused)]
fn main() {
/// Included in every outgoing packet. Tells the peer which of their
/// recent packets we received.
pub struct AckVector {
    /// Sequence number of the most recently received packet (bit 0).
    pub latest_recv_seq: u32,
    /// Bitmask: bit N = 1 means we received (latest_recv_seq - N).
    /// 64 bits covers the last 64 packets at 30 tps ≈ ~2 seconds of history.
    pub received_mask: u64,
}
}

Why ack vectors over TCP-style cumulative ACKs:

• No head-of-line blocking. TCP’s cumulative ACK stalls retransmission decisions when a single early packet is lost but later packets arrive fine. Ack vectors give per-packet reception status instantly.
• Sender-side retransmit decisions. The sender has full information about which packets were received and decides what to retransmit. The receiver never requests retransmission — it simply reports what it got. This keeps the receiver stateless with respect to reliability.
• Natural fit for UDP. Ack vectors assume an unreliable, unordered transport — exactly what UDP provides. On reliable transports (WebSocket), the ack vector still works but retransmit timers never fire (same “always run reliability” principle from D054).
• Compact. A 64-bit bitmask + 4-byte sequence number = 12 bytes per packet. TCP’s SACK option can be up to 40 bytes.

Retransmission: When the sender sees a gap in the ack vector (bit = 0 for a packet older than the latest ACK’d), it schedules retransmission. Retransmission uses exponential backoff per packet. The retransmit buffer is the same circular buffer used for frame resilience (last N ticks of sent data).

Per-Ack RTT Measurement (from Valve GNS)

Each outgoing packet embeds a small delay field — the time elapsed between receiving the peer’s most recent packet and sending this response. The peer subtracts this processing delay from the observed round-trip to compute a precise one-way latency estimate:

#![allow(unused)]
fn main() {
/// Embedded in every packet header alongside the ack vector.
pub struct PeerDelay {
    /// Microseconds between receiving the peer's latest packet
    /// and sending this packet. The peer uses this to compute RTT:
    /// RTT = (time_since_we_sent_the_acked_packet) - peer_delay
    pub delay_us: u16,
}
}

Why this matters: Traditional RTT measurement requires dedicated ping/pong packets or timestamps that consume bandwidth. By embedding delay in every ack, RTT is measured continuously on every packet exchange — no separate ping packets needed. This provides smoother, more accurate latency data for adaptive run-ahead (see above) and removes the ~50ms ping interval overhead. The technique is standard in Valve’s GNS and is also used by QUIC (RFC 9000).

Nagle-Style Order Batching (from Valve GNS)

Player orders are not sent immediately on input — they are batched within each tick window and flushed at tick boundaries:

#![allow(unused)]
fn main() {
/// Order batching within a tick window.
/// Orders accumulate in a buffer and are flushed as a single packet
/// at the tick boundary. This reduces packet count by ~5-10x during
/// burst input (selecting and commanding multiple groups rapidly).
pub struct OrderBatcher {
    /// Orders accumulated since last flush.
    pending: Vec<TimestampedOrder>,
    /// Flush when the tick boundary arrives (external trigger from game loop).
    /// Unlike TCP Nagle (which flushes on ACK), we flush on a fixed cadence
    /// aligned to the sim tick rate — deterministic, predictable latency.
    tick_rate: Duration,
}
}

Unlike TCP’s Nagle algorithm (which flushes on receiving an ACK — coupling send timing to network conditions), IC flushes on a fixed tick cadence. This gives deterministic, predictable send timing: all orders within a tick window are batched into one packet, sent at the tick boundary. At 30 tps, this means at most ~33ms of batching delay — well within the adaptive run-ahead window and invisible to the player. The technique is validated by Valve’s GNS batching strategy (see research/valve-github-analysis.md § 1.7).

Wire Format: Delta-Compressed TLV (from C&C Generals)

Inspired by C&C Generals’ NetPacket format (see research/generals-zero-hour-netcode-analysis.md), the native wire format uses delta-compressed tag-length-value (TLV) encoding:

• Tag bytes — single ASCII byte identifies the field: Type, K(ticK), Player, Sub-tick, Data
• Delta encoding — fields are only written when they differ from the previous order in the same packet. If the same player sends 5 orders on the same tick, the player ID and tick number are written once.
• Empty-tick compression — ticks with no orders compress to a single byte (Generals used Z). In a typical RTS, ~80% of ticks have zero orders from any given player.
• Varint encoding — integer fields use variable-length encoding (LEB128) where applicable. Small values (tick deltas, player indices) compress to 1-2 bytes instead of fixed 4-8 bytes. Integers that are typically small (order counts, sub-tick offsets) benefit most; fixed-size fields (hashes, signatures) remain fixed.
• MTU-aware packet sizing — packets stay under 476 bytes (single IP fragment, no UDP fragmentation). Fragmented UDP packets multiply loss probability — if any fragment is lost, the entire packet is dropped.
• Transport-agnostic framing — the wire format is independent of the underlying transport (UDP, WebSocket, QUIC). The same TLV encoding works on all transports; only the packet delivery mechanism changes (D054). This follows GNS’s approach of transport-agnostic SNP (Steam Networking Protocol) frames (see research/valve-github-analysis.md § Part 1).

For typical RTS traffic (0-2 orders per player per tick, long stretches of idle), this compresses wire traffic by roughly 5-10x compared to naively serializing every TimestampedOrder.

For cross-engine play, the wire format is abstracted behind an OrderCodec trait — see 07-CROSS-ENGINE.md.

Message Lanes (from Valve GNS)

Not all network messages have equal priority. Valve’s GNS introduces lanes — independent logical streams within a single connection, each with configurable priority and weight. IC adopts this concept for its relay protocol to prevent low-priority traffic from delaying time-critical orders.

#![allow(unused)]
fn main() {
/// Message lanes — independent priority streams within a Transport connection.
/// Each lane has its own send queue. The transport drains queues by priority
/// (higher first) and weight (proportional bandwidth among same-priority lanes).
///
/// Lanes are a `NetworkModel` concern, not a `Transport` concern — Transport
/// provides a single byte pipe; NetworkModel multiplexes lanes over it.
/// This keeps Transport implementations simple (D054).
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub enum MessageLane {
    /// Tick orders — highest priority, real-time critical.
    /// Delayed orders cause Idle substitution (anti-lag-switch).
    Orders = 0,
    /// Sync hashes, ack vectors, RTT measurements — protocol control.
    /// Must arrive promptly for desync detection and adaptive run-ahead.
    Control = 1,
    /// Chat messages, player status updates, lobby state.
    /// Important but not time-critical — can tolerate ~100ms extra delay.
    Chat = 2,
    /// Voice-over-IP frames (Opus-encoded). Real-time but best-effort —
    /// dropped frames use Opus PLC, not retransmit. See D059.
    Voice = 3,
    /// Replay data, observer feeds, telemetry.
    /// Lowest priority — uses spare bandwidth only.
    Bulk = 4,
}

/// Lane configuration — priority and weight determine scheduling.
pub struct LaneConfig {
    /// Higher priority lanes are drained first (0 = highest).
    pub priority: u8,
    /// Weight for proportional bandwidth sharing among same-priority lanes.
    /// E.g., two lanes at priority 1 with weights 3 and 1 get 75%/25% of
    /// remaining bandwidth after higher-priority lanes are satisfied.
    pub weight: u8,
    /// Per-lane buffering limit (bytes). If exceeded, oldest messages
    /// in the lane are dropped (unreliable lanes) or the lane stalls
    /// (reliable lanes). Prevents low-priority bulk data from consuming
    /// unbounded memory.
    pub buffer_limit: usize,
}
}

Default lane configuration:

The Orders and Control lanes share the highest priority tier — both are drained before any Chat or Bulk data is sent. Chat and Voice share priority tier 1 with a 2:1 weight ratio (voice gets more bandwidth because it’s time-sensitive). This ensures that a player spamming chat messages, voice traffic, or a spectator feed generating bulk data never delays order delivery. The lane system is optional for LocalNetwork and MemoryTransport (where bandwidth is unlimited), but critical for the relay deployment where bandwidth to each client is finite. See decisions/09g/D059-communication.md for the full VoIP architecture.

Relay server poll groups: In a relay deployment serving multiple concurrent games, each game session’s connections are grouped into a poll group (terminology from GNS). The relay’s event loop polls all connections within a poll group together, processing messages for one game session in a batch before moving to the next. This improves cache locality (all state for one game is hot in cache during its processing window) and simplifies per-game rate limiting. The poll group concept is internal to the relay server — clients don’t know or care whether they share a relay with other games.

Desync Detection & Debugging

Desyncs are the hardest problem in lockstep netcode. OpenRA has 135+ desync issues in their tracker — they hash game state per frame (via [VerifySync] attribute) but their sync report buffer is only 7 frames deep, which often isn’t enough to capture the divergence point. Our architecture makes desyncs both detectable AND diagnosable, drawing on 20+ years of OpenTTD’s battle-tested desync debugging infrastructure.

Dual-Mode State Hashing

Every tick, each client hashes their sim state. But a full state_hash() over the entire ECS world is expensive. We use a two-tier approach (validated by both OpenTTD and 0 A.D.):

• Primary: RNG state comparison. Every sync frame, clients exchange their deterministic RNG seed. If the RNG diverges, the sim has diverged — this catches ~99% of desyncs at near-zero cost. The RNG is advanced by every stochastic sim operation (combat rolls, scatter patterns, AI decisions), so any state divergence quickly contaminates it.
• Fallback: Full state hash. Periodically (every N ticks, configurable — default 120, ~4 seconds at 30 tps) or when RNG drift is detected, compute and compare a full state_hash(). This catches the rare case where a desync affects only deterministic state that doesn’t touch the RNG.

The relay server (or P2P peers) compares hashes. On mismatch → desync detected at a specific tick. Because the sim is snapshottable (D010), dump full state and diff to pinpoint exact divergence — entity by entity, component by component.

Merkle Tree State Hashing (Phase 2+)

A flat state_hash() tells you that state diverged, but not where. Diagnosing which entity or subsystem diverged requires a full state dump and diff — expensive for large games (500+ units, ~100KB+ of serialized state). IC addresses this by structuring the state hash as a Merkle tree, enabling binary search over state within a tick — not just binary search over ticks (which is what OpenTTD’s snapshot bisection already provides).

The Merkle tree partitions ECS state by archetype (or configurable groupings — e.g., per-player, per-subsystem). Each leaf is the hash of one archetype’s serialized components. Interior nodes are SHA-256(left_child || right_child) in the full debug representation. For live sync checks, IC transmits a compact 64-bit fast sync hash (u64) derived from the Merkle root (or flat hash in Phase 2), preserving low per-tick bandwidth. Higher debug levels may include full 256-bit node hashes in DesyncDebugReport payloads for stronger evidence and better tooling. This costs the same as a flat hash (every byte is still hashed once) — the tree structure is overhead-free for the common case where hashes match.

When hashes don’t match, the tree enables logarithmic desync localization:

1. Clients exchange the Merkle root’s fast sync hash (same as today — one u64 per sync frame).
2. On mismatch, clients exchange interior node hashes at depth 1 (2 hashes).
3. Whichever subtree differs, descend into it — exchange its children (2 more hashes).
4. Repeat until reaching a leaf: the specific archetype (or entity group) that diverged.

For a sim with 32 archetypes, this requires ~5 round trips of 2 hashes each (10 hashes total, ~320 bytes) instead of a full state dump (~100KB+). The desync report then contains the exact archetype and a compact diff of its components — actionable information, not a haystack.

#![allow(unused)]
fn main() {
/// Merkle tree over ECS state for efficient desync localization.
pub struct StateMerkleTree {
    /// Leaf fast hashes (u64 truncations / fast-sync form), one per archetype or entity group.
    /// Full SHA-256 nodes may be computed on demand for debug reports.
    pub leaves: Vec<(ArchetypeLabel, u64)>,
    /// Interior node fast hashes (computed bottom-up).
    pub nodes: Vec<u64>,
    /// Root fast hash — this is the state_hash() used for live sync comparison.
    pub root: u64,
}

impl StateMerkleTree {
    /// Returns the path of hashes needed to prove a specific leaf's
    /// membership in the tree. Used for selective verification.
    pub fn proof_path(&self, leaf_index: usize) -> Vec<u64> { /* ... */ }
}
}

This pattern comes from blockchain state tries (Ethereum’s Patricia-Merkle trie, Bitcoin’s Merkle trees for transaction verification), adapted for game state. The original insight — that a tree structure over hashed state enables O(log N) divergence localization without transmitting full state — is one of the few genuinely useful ideas to emerge from the Web3 ecosystem. IC uses it for desync debugging, not consensus.

Selective replay verification also benefits: a viewer can verify that a specific tick’s state is authentic by checking the Merkle path from the tick’s root hash to the replay’s signature chain — without replaying the entire game. See 05-FORMATS.md § Signature Chain for how this integrates with relay-signed replays.

Phase: Flat state_hash() ships in Phase 2 (sufficient for detection). Merkle tree structure added in Phase 2+ when desync diagnosis tooling is built. The tree is a strict upgrade — same root hash, more information on mismatch.

Debug Levels (from OpenTTD)

Desync diagnosis uses configurable debug levels. Each level adds overhead, so higher levels are only enabled when actively hunting a bug:

#![allow(unused)]
fn main() {
/// Debug levels for desync diagnosis. Set via config or debug console.
/// Each level includes all lower levels.
pub enum DesyncDebugLevel {
    /// Level 0: No debug overhead. RNG sync only. Production default.
    Off = 0,
    /// Level 1: Log all orders to a structured file (order-log.bin).
    /// Enables order-log replay for offline diagnosis.
    OrderLog = 1,
    /// Level 2: Run derived-state validation every tick.
    /// Checks that caches (spatial hash, fog grid, pathfinding data)
    /// match authoritative state. Zero production impact — debug only.
    CacheValidation = 2,
    /// Level 3: Save periodic snapshots at configurable interval.
    /// Names: desync_{game_seed}_{tick}.snap for bisection.
    PeriodicSnapshots = 3,
}
}

Level 1 — Order logging. Every order is logged to a structured binary file with the tick number and sync state at that tick. This enables order-log replay: load the initial state + replay orders, comparing logged sync state against replayed state at each tick. When they diverge, you’ve found the exact tick where the desync was introduced. OpenTTD has used this technique for 20+ years — it’s the most effective desync diagnosis tool ever built for lockstep games.

Level 2 — Cache validation. Systematic validation of derived/cached data against source-of-truth data every tick. The spatial hash, fog-of-war grid, pathfinding caches, and any other precomputed data are recomputed from authoritative ECS state and compared. A mismatch means a cache update was missed somewhere — a cache bug, not a sim bug. OpenTTD’s CheckCaches() function validates towns, companies, vehicles, and stations this way. This catches an entire class of bugs that full-state hashing misses (the cache diverges, but the authoritative state is still correct — until something reads the stale cache).

Level 3 — Periodic snapshots. Save full sim snapshots at a configurable interval (default: every 300 ticks, ~10 seconds). Snapshots are named desync_{game_seed}_{tick}.snap — sorting by seed groups snapshots from the same game, sorting by tick within a game enables binary search for the divergence point. This is OpenTTD’s dmp_cmds_XXXXXXXX_YYYYYYYY.sav pattern adapted for IC.

Desync Log Transfer Protocol

When a desync is detected, debug data must be collected from all clients — comparing state from just one side tells you that the states differ, but not which client diverged (or whether both did). 0 A.D. highlighted this gap: their desync reports were one-sided, requiring manual coordination between players to share debug dumps (see research/0ad-warzone2100-netcode-analysis.md).

IC automates cross-client desync data exchange through the relay:

1. Detection: Relay detects hash mismatch at tick T.
2. Collection request: Relay sends DesyncDebugRequest { tick: T, level: DesyncDebugLevel } to all clients.
3. Client response: Each client responds with a DesyncDebugReport containing its state hash, RNG state, Merkle node hashes (if Merkle tree is active), and optionally a compressed snapshot of the diverged archetype (identified by Merkle tree traversal).
4. Relay aggregation: Relay collects reports from all clients, computes a diff summary, and distributes the aggregated report back to all clients (or saves it for post-match analysis).

#![allow(unused)]
fn main() {
pub struct DesyncDebugReport {
    pub player: PlayerId,
    pub tick: u64,
    pub state_hash: u64,
    pub rng_state: u64,
    pub merkle_nodes: Option<Vec<(ArchetypeLabel, u64)>>,  // if Merkle tree active
    pub diverged_archetypes: Option<Vec<CompressedArchetypeSnapshot>>,
    pub order_log_excerpt: Vec<TimestampedOrder>,  // orders around tick T
}
}

In P2P mode, the host collects reports from all peers. For offline diagnosis, the report is written to desync_report_{game_seed}_{tick}.json alongside the snapshot files.

Serialization Test Mode (Determinism Verification)

A development-only mode that runs two sim instances in parallel, both processing the same orders, and compares their state after every tick. If the states ever diverge, the sim has a non-deterministic code path. This pattern is used by 0 A.D.’s test infrastructure (see research/0ad-warzone2100-netcode-analysis.md):

#![allow(unused)]
fn main() {
/// Debug mode: run dual sims to catch non-determinism.
/// Enabled via `--dual-sim` flag. Debug builds only.
#[cfg(debug_assertions)]
pub struct DualSimVerifier {
    pub primary: Simulation,
    pub shadow: Simulation,  // cloned from primary at game start
}

#[cfg(debug_assertions)]
impl DualSimVerifier {
    pub fn tick(&mut self, orders: &TickOrders) {
        self.primary.apply_tick(orders);
        self.shadow.apply_tick(orders);
        assert_eq!(
            self.primary.state_hash(), self.shadow.state_hash(),
            "Determinism violation at tick {}! Primary and shadow sims diverged.",
            orders.tick
        );
    }
}
}

This catches non-determinism immediately — no need to wait for a multiplayer desync report. Particularly valuable during development of new sim systems. The shadow sim doubles memory usage and CPU time, so this is never enabled in release builds or production. Running the test suite under dual-sim mode is a CI gate for Phase 2+.

Adaptive Sync Frequency

The full state hash comparison frequency adapts based on game phase stability (inspired by the adaptive snapshot rate patterns observed across multiple engines):

• High frequency (every 30 ticks, ~1 second): During the first 60 seconds of a match and immediately after any player reconnects — state divergence is most likely during transitions.
• Normal frequency (every 120 ticks, ~4 seconds): Standard play. Sufficient to catch divergence within a few seconds.
• Low frequency (every 300 ticks, ~10 seconds): Late-game with large unit counts, where the hash computation cost is non-trivial. The RNG sync check (near-zero cost) still runs every tick.

The relay can also request an out-of-band sync check after specific events (e.g., a player reconnection completes, a mod hot-reloads script).

Validation Purity Enforcement

Order validation (D012, 06-SECURITY.md § Vulnerability 2) must have zero side effects. OpenTTD learned this the hard way — their “test run” of commands sometimes modified state, causing desyncs that took years to find. In debug builds, we enforce purity automatically:

#![allow(unused)]
fn main() {
#[cfg(debug_assertions)]
fn validate_order_checked(&mut self, player: PlayerId, order: &PlayerOrder) -> OrderValidity {
    let hash_before = self.state_hash();
    let result = self.validate_order(player, order);
    let hash_after = self.state_hash();
    assert_eq!(hash_before, hash_after,
        "validate_order() modified sim state! Order: {:?}, Player: {:?}", order, player);
    result
}
}

This debug_assert catches validation impurity at the moment it happens, not weeks later when a desync report arrives. Zero cost in release builds.

Disconnect Handling (from C&C Generals)

Graceful disconnection is a first-class protocol concern, not an afterthought. Inspired by Generals’ 7-type disconnect protocol (see research/generals-zero-hour-netcode-analysis.md), we handle disconnects deterministically:

With relay: The relay server detects disconnection via heartbeat timeout and notifies all clients of the specific tick on which the player is removed. All clients process the removal on the same tick — deterministic.

P2P (without relay): When a player appears unresponsive:

1. Ping verification — all players ping the suspect to confirm unreachability (prevents false blame from asymmetric routing)
2. Blame attribution — ping results determine who is actually disconnected vs. who is just slow
3. Coordinated removal — remaining players agree on a specific tick number to remove the disconnected player, ensuring all sims stay synchronized
4. Historical frame buffer — recent frame data is preserved so if the disconnecting player was also the packet router (P2P star topology), other players can recover missed frames

For competitive/ranked games, disconnect blame feeds into the match result: the blamed player takes the loss; remaining players can optionally continue or end the match without penalty.

Reconnection

A disconnected player can rejoin a game in progress. This uses the same snapshottable sim (D010) that enables save games and replays:

1. Reconnecting client contacts the relay (or host in P2P). The relay verifies identity via the session key established at game start.
2. Relay/host coordinates state transfer. In P2P, the host is the snapshot source. In relay mode, the relay does not run the sim, so it selects a snapshot donor from active clients (typically a healthy, low-latency peer) and requests a transfer at a known tick boundary.
3. Donor creates snapshot of its current sim state and streams it (via relay in relay mode) to the reconnecting client. Any pending orders queued during the snapshot are sent alongside it (from OpenTTD: NetworkSyncCommandQueue), closing the gap between snapshot creation and delivery.
4. Snapshot verification before load. The reconnecting client verifies the snapshot tick/hash against relay-coordinated sync data (latest agreed sync hash, or an out-of-band sync check requested by the relay immediately before transfer). If verification fails, the relay retries with a different donor or aborts reconnection.
5. Client loads the snapshot and enters a catchup state, processing ticks at accelerated speed until it reaches the current tick.
6. Client becomes active once it’s within one tick of the server. Orders resume flowing normally.

#![allow(unused)]
fn main() {
pub enum ClientStatus {
    Connecting,          // Transport established, awaiting authentication
    Authorized,          // Identity verified, awaiting state transfer
    Downloading,         // Receiving snapshot
    CatchingUp,          // Processing ticks at accelerated speed
    Active,              // Fully synced, orders flowing
}
}

The relay server sends keepalive messages to the reconnecting client during download (prevents timeout), proxies donor snapshot chunks in relay mode, and queues that player’s slot as PlayerOrder::Idle until catchup completes. Other players experience no interruption — the game never pauses for a reconnection.

Frame consumption smoothing during catchup: When a reconnecting client is processing ticks at accelerated speed (CatchingUp state), it must balance sim catchup against rendering responsiveness. If the client devotes 100% of CPU to sim ticks, the screen freezes during catchup — the player sees a frozen frame for seconds, then suddenly jumps to the present. Spring Engine solved this with an 85/15 split: 85% of each frame’s time budget goes to sim catchup ticks, 15% goes to rendering the current state (see research/spring-engine-netcode-analysis.md). IC adopts a similar approach:

#![allow(unused)]
fn main() {
/// Controls how the client paces sim tick processing during reconnection.
/// Higher values = faster catchup but choppier rendering.
pub struct CatchupConfig {
    pub sim_budget_pct: u8,    // % of frame time for sim ticks (default: 80)
    pub render_budget_pct: u8, // % of frame time for rendering (default: 20)
    pub max_ticks_per_frame: u32, // Hard cap on sim ticks per render frame (default: 30)
}
}

The reconnecting player sees a fast-forward of the game (like a time-lapse replay) rather than a frozen screen followed by a jarring jump. The sim/render ratio can be tuned per platform — mobile clients may need a 70/30 split for acceptable visual feedback.

Timeout: If reconnection doesn’t complete within a configurable window (default: 60 seconds), the player is permanently dropped. This prevents a malicious player from cycling disconnect/reconnect to disrupt the game indefinitely.

Visual Prediction (Cosmetic, Not Sim)

The render layer provides instant visual feedback on player input, before the order is confirmed by the network:

#![allow(unused)]
fn main() {
// ic-render: immediate visual response to click
fn on_move_order_issued(click_pos: WorldPos, selected_units: &[Entity]) {
    // Show move marker immediately
    spawn_move_marker(click_pos);
    
    // Start unit turn animation toward target (cosmetic only)
    for unit in selected_units {
        start_turn_preview(unit, click_pos);
    }
    
    // Selection acknowledgement sound plays instantly
    play_unit_response_audio(selected_units);
    
    // The actual sim order is still in the network pipeline.
    // Units will begin real movement when the order is confirmed next tick.
    // The visual prediction bridges the gap so the game feels instant.
}
}

This is purely cosmetic — the sim doesn’t advance until the confirmed order arrives. But it eliminates the perceived lag. The selection ring snaps, the unit rotates, the acknowledgment voice plays — all before the network round-trip completes.

Cosmetic RNG Separation

Visual prediction and all render-side effects (particles, muzzle flash variation, shell casing scatter, smoke drift, death animations, idle fidgets, audio pitch variation) use a separate non-deterministic RNG — completely independent of the sim’s deterministic PRNG. This is a critical architectural boundary (validated by Hypersomnia’s dual-RNG design — see research/veloren-hypersomnia-openbw-ddnet-netcode-analysis.md):

#![allow(unused)]
fn main() {
// ic-sim: deterministic — advances identically on all clients
pub struct SimRng(pub StdRng); // seeded once at game start, never re-seeded

// ic-render: non-deterministic — each client generates different particles
pub struct CosmeticRng(pub ThreadRng); // seeded from OS entropy per client
}

Why this matters: If render code accidentally advances the sim RNG (e.g., a particle system calling sim_rng.gen() to randomize spawn positions), the sim desynchronizes — different clients render different particle counts, advancing the RNG by different amounts. This is an insidious desync source because the game looks correct but the RNG state has silently diverged. Separating the RNGs makes this bug structurally impossible — render code simply cannot access SimRng.

Predictability tiers for visual effects:

Effects in the “cosmetic-free” tier can differ between clients without affecting gameplay — Player A sees 47 smoke particles, Player B sees 52, neither notices. Effects in “cosmetic-synced” are rare but exist when visual consistency matters for competitive readability (e.g., a Tesla coil’s charge-up animation must match across spectator views).

Why It Feels Faster Than OpenRA

Every lockstep RTS has inherent input delay — the game must wait for all players’ orders before advancing. This is architectural, not a bug. But how much delay, and who pays for it, varies dramatically.

OpenRA’s Stalling Model

OpenRA uses TCP-based lockstep where the game advances only when ALL clients have submitted orders for the current net frame (OrderManager.TryTick() checks pendingOrders.All(...)):

Tick 50: waiting for Player A's orders... ✓ (10ms)
         waiting for Player B's orders... ✓ (15ms)
         waiting for Player C's orders... ⏳ (280ms — bad WiFi)
         → ALL players frozen for 280ms. Everyone suffers.

Additionally (verified from source):

• Orders are batched every NetFrameInterval frames (not every tick), adding batching delay
• The server adds OrderLatency frames to every order (default 1 for local, higher for MP game speeds)
• OrderBuffer dynamically adjusts per-player TickScale (up to 10% speedup) based on delivery timing
• Even in single player, EchoConnection projects orders 1 frame forward
• C# GC pauses add unpredictable jank on top of the architectural delay

The perceived input lag when clicking units in OpenRA is estimated at ~100-200ms — a combination of intentional lockstep delay, order batching, and runtime overhead.

Our Model: No Stalling

The relay server owns the clock. It broadcasts tick orders on a fixed deadline — missed orders are replaced with PlayerOrder::Idle:

Tick 50: relay deadline = 80ms
         Player A orders arrive at 10ms  → ✓ included
         Player B orders arrive at 15ms  → ✓ included  
         Player C orders arrive at 280ms → ✗ missed deadline → Idle
         → Relay broadcasts at 80ms. No stall. Player C's units idle.

Honest players on good connections always get responsive gameplay. A lagging player hurts only themselves.

Input Latency Comparison

OpenRA values are from source code analysis, not runtime benchmarks. Tick processing times are estimates.

The NetworkModel Trait

The netcode described above is expressed as a trait because it gives us testability, single-player support, and deployment flexibility and preserves architectural escape hatches. The sim and game loop never know which deployment mode is running, and they also don’t need to know if deferred milestones introduce (outside the M4 minimal-online slice):

• a compatibility bridge/protocol adapter for cross-engine experiments (e.g., community interop with legacy game versions or OpenRA)
• a replacement default netcode if production evidence reveals a serious flaw or a better architecture

The product still ships one recommended/default multiplayer path; the trait exists so changing the path under a deferred milestone does not require touching ic-sim or the game loop.

#![allow(unused)]
fn main() {
pub trait NetworkModel: Send + Sync {
    /// Local player submits an order
    fn submit_order(&mut self, order: TimestampedOrder);
    /// Poll for the next tick's confirmed orders (None = not ready yet)
    fn poll_tick(&mut self) -> Option<TickOrders>;
    /// Report local fast sync hash (`u64`) for desync detection
    fn report_sync_hash(&mut self, tick: u64, hash: u64);
    /// Connection/sync status
    fn status(&self) -> NetworkStatus;
    /// Diagnostic info (latency, packet loss, etc.)
    fn diagnostics(&self) -> NetworkDiagnostics;
}
}

Deployment Modes

The same netcode runs in five modes. The first two are utility adapters (no network involved). The last three are real multiplayer deployments of the same protocol:

LockstepNetwork, EmbeddedRelayNetwork, and RelayLockstepNetwork implement the same netcode. The differences are topology and trust:

• LockstepNetwork — P2P direct connections (full mesh for 2-3 players). No relay, no time authority. Simplest, best for LAN.
• EmbeddedRelayNetwork — the host’s game client runs RelayCore (see above) as a listen server. Other players connect to the host. Full sub-tick ordering, anti-lag-switch, and replay signing — same as a dedicated relay. The host plays normally while serving. Ideal for casual/community play: “Host Game” button, zero external infrastructure.
• RelayLockstepNetwork — clients connect to a standalone relay server on trusted infrastructure. Required for ranked/competitive play (host can’t be trusted with relay authority). Recommended for internet play.

All three use adaptive run-ahead, frame resilience, delta-compressed TLV, and Ed25519 signing. The two relay-based modes (EmbeddedRelayNetwork and RelayLockstepNetwork) share identical RelayCore logic — connecting clients use RelayLockstepNetwork in both cases and cannot distinguish between them.

These deployments are the current lockstep family. The NetworkModel trait intentionally keeps room for deferred non-default implementations (e.g., bridge adapters, rollback experiments, fog-authoritative tournament servers) without changing sim code or invalidating the architectural boundary. Those paths are optional and not part of M4 exit criteria.

Example Deferred Adapter: NetcodeBridgeModel (Compatibility Bridge)

To make the architectural intent concrete, here is the shape of a deferred compatibility bridge implementation. This is not a promise of full cross-play with original RA/OpenRA; it is an example of how the NetworkModel boundary allows experimentation without touching ic-sim. Planned-deferral scope: cross-engine bridge experiments are tied to M7.NET.CROSS_ENGINE_BRIDGE_AND_TRUST / M11 visual+interop follow-ons and are unranked by default unless a separate explicit decision certifies a mode.

Use cases this enables (deferred / optional, M7+ and M11):

• Community-hosted bridge experiments for legacy game versions or OpenRA
• Discovery-layer interop plus limited live-play compatibility prototypes
• Transitional migrations if IC changes its default netcode under a separately approved deferred milestone

#![allow(unused)]
fn main() {
/// Example deferred adapter. Not part of the initial shipping set.
/// Wraps a protocol/transport bridge and translates between an external
/// protocol family and IC's canonical TickOrders interface.
pub struct NetcodeBridgeModel<B: ProtocolBridge> {
    bridge: B,
    inbound_ticks: VecDeque<TickOrders>,
    diagnostics: NetworkDiagnostics,
    status: NetworkStatus,
    // Capability negotiation / compatibility flags:
    // supported_orders, timing_model, hash_mode, etc.
}

impl<B: ProtocolBridge> NetworkModel for NetcodeBridgeModel<B> {
    fn submit_order(&mut self, order: TimestampedOrder) {
        self.bridge.submit_ic_order(order);
    }

    fn poll_tick(&mut self) -> Option<TickOrders> {
        self.bridge.poll_bridge();
        self.inbound_ticks.pop_front()
    }

    fn report_sync_hash(&mut self, tick: u64, hash: u64) {
        self.bridge.report_ic_sync_hash(tick, hash);
    }

    fn status(&self) -> NetworkStatus { self.status.clone() }
    fn diagnostics(&self) -> NetworkDiagnostics { self.diagnostics.clone() }
}
}

What a bridge adapter is responsible for:

• Protocol translation — external wire messages ↔ IC TimestampedOrder / TickOrders
• Timing model adaptation — map external timing/order semantics into IC tick/sub-tick expectations (or degrade gracefully with explicit fairness limits)
• Capability negotiation — detect unsupported features/order types and reject, stub, or map them explicitly
• Authority/trust policy — declare whether the bridge is relay-authoritative, P2P-trust, or observer-only
• Diagnostics — expose compatibility state, dropped/translated orders, and fidelity warnings via NetworkDiagnostics

What a bridge adapter is NOT responsible for:

• Making simulations identical across engines (D011 still applies)
• Mutating ic-sim rules to emulate foreign bugs/quirks in core engine code
• Bypassing ranked trust rules (bridge modes are unranked by default unless a separate explicit decision (Dxxx / Pxxx) certifies one)
• Hiding incompatibilities — unsupported semantics must be visible to users/operators

Practical expectation: Early bridge modes are most likely to ship (if ever) as observer/replay/discovery integrations first, then limited casual play experiments, with strict capability constraints. Competitive/ranked bridge play would require a separate explicit decision and a much stronger certification story.

Sub-tick ordering in P2P: Without a neutral relay, there is no central time authority. Instead, each client sorts orders deterministically by (sub_tick_time, player_id) — the player ID tiebreaker ensures all clients produce the same canonical order even with identical timestamps. This is slightly less fair than relay ordering (clock skew between peers can bias who “clicked first”), but acceptable for LAN/small-group play where latencies are low. The relay-based modes (embedded or dedicated) eliminate this issue entirely with neutral time authority, and additionally provide lag-switch protection, NAT traversal, and signed replays.

Single-Player: Zero Delay

LocalNetwork processes orders on the very next tick with zero scheduling delay:

#![allow(unused)]
fn main() {
impl NetworkModel for LocalNetwork {
    fn submit_order(&mut self, order: TimestampedOrder) {
        // Order goes directly into the next tick — no delay, no projection
        self.pending.push(order);
    }
    
    fn poll_tick(&mut self) -> Option<TickOrders> {
        // Always ready — no waiting for other clients
        Some(TickOrders {
            tick: self.tick,
            orders: std::mem::take(&mut self.pending),
        })
    }
}
}

At 30 tps, a click-to-move in single player is confirmed within ~33ms — imperceptible to humans (reaction time is ~200ms). Combined with visual prediction, the game feels instant.

Replay Playback

Replays are a natural byproduct of the architecture:

Replay file = initial state + sequence of TickOrders
Playback = feed TickOrders through Simulation via ReplayPlayback NetworkModel

Replays are signed by the relay server for tamper-proofing (see 06-SECURITY.md).

Background Replay Writer

During live games, the replay file is written by a background writer using a lock-free queue — the sim thread never blocks on I/O. This prevents disk write latency from causing frame hitches (a problem observed in 0 A.D.’s synchronous replay recording — see research/0ad-warzone2100-netcode-analysis.md):

#![allow(unused)]
fn main() {
/// Non-blocking replay recorder. The sim thread pushes tick frames
/// into a lock-free queue; a background thread drains and writes.
pub struct BackgroundReplayWriter {
    queue: crossbeam::channel::Sender<ReplayTickFrame>,
    handle: std::thread::JoinHandle<()>,
}

impl BackgroundReplayWriter {
    /// Called from the sim thread after each tick. Never blocks.
    pub fn record_tick(&self, frame: ReplayTickFrame) {
        // crossbeam bounded channel — if the writer falls behind,
        // oldest frames are still in memory (not dropped). The buffer
        // is sized for ~10 seconds of ticks (300 frames at 30 tps).
        let _ = self.queue.try_send(frame);
    }
}
}

Security (V45): try_send silently drops frames when the channel is full — contradicting the code comment. Lost frames break the Ed25519 signature chain (V4). Mitigations: track frame loss count in replay header, use send_timeout(frame, 5ms) instead of try_send, mark replays with lost frames as incomplete (playable but not ranked-verifiable), handle signature chain gaps explicitly. See 06-SECURITY.md § Vulnerability 45.

The background thread writes frames incrementally — the .icrep file is always valid (see 05-FORMATS.md § Replay File Format). If the game crashes, the replay up to the last flushed frame is recoverable. On game end, the writer flushes remaining frames, writes the final header (total ticks, final state hash), and closes the file.

Deferred Optional Architectures

The NetworkModel trait also keeps the door open for fundamentally different networking approaches as deferred optional work. These are NOT the same netcode — they are genuinely different architectures with different trade-offs. They are outside M4 and M7 core lockstep productization scope unless promoted by a separate explicit decision and execution-overlay placement.

Fog-Authoritative Server (anti-maphack)

Server runs full sim, sends each client only entities they should see. Breaks pure lockstep (clients run partial sims), requires server compute per game. Uses Fiedler’s priority accumulator (2015) for bandwidth-bounded entity updates — units in combat are highest priority, distant static structures are deferred but eventually sent. See 06-SECURITY.md § Vulnerability 1 for the full design including entity prioritization and traffic class segregation.

Rollback / GGPO-Style (experimental)

Requires snapshottable sim (already designed via D010). Client predicts with local input, rolls back on misprediction. Expensive for RTS (re-simulating hundreds of entities), but feasible with Rust’s performance. See GGPO documentation for reference implementation.

Cross-Engine Protocol Adapter

A ProtocolAdapter<N> wrapper translates between Iron Curtain’s native protocol and other engines’ wire formats (e.g., OpenRA). Uses the OrderCodec trait for format translation. See 07-CROSS-ENGINE.md for full design.

OrderCodec: Wire Format Abstraction

For cross-engine play and protocol versioning, the wire format is abstracted behind a trait:

#![allow(unused)]
fn main() {
pub trait OrderCodec: Send + Sync {
    fn encode(&self, order: &TimestampedOrder) -> Result<Vec<u8>>;
    fn decode(&self, bytes: &[u8]) -> Result<TimestampedOrder>;
    fn protocol_id(&self) -> ProtocolId;
}

/// Native format — fast, compact, versioned (delta-compressed TLV)
pub struct NativeCodec { version: u32 }

/// Translates to/from OpenRA's wire format
pub struct OpenRACodec {
    order_map: OrderTranslationTable,
    coord_transform: CoordTransform,
}
}

See 07-CROSS-ENGINE.md for full cross-engine compatibility design.

Development Tools

Network Simulation

Inspired by Generals’ debug network simulation features, all NetworkModel implementations support artificial network condition injection:

#![allow(unused)]
fn main() {
/// Configurable network conditions for testing. Applied at the transport layer.
/// Only available in debug/development builds — compiled out of release.
pub struct NetworkSimConfig {
    pub latency_ms: u32,          // Artificial one-way latency added to each packet
    pub jitter_ms: u32,           // Random ± jitter on top of latency
    pub packet_loss_pct: f32,     // Percentage of packets silently dropped (0.0–100.0)
    pub corruption_pct: f32,      // Percentage of packets with random bit flips
    pub bandwidth_limit_kbps: Option<u32>,  // Throttle outgoing bandwidth
    pub duplicate_pct: f32,       // Percentage of packets sent twice
    pub reorder_pct: f32,         // Percentage of packets delivered out of order
}
}

This is invaluable for testing edge cases (desync under packet loss, adaptive run-ahead behavior, frame resend logic) without needing actual bad networks. Accessible via debug console or lobby settings in development builds.

Diagnostic Overlay

A real-time network health display (inspired by Quake 3’s lagometer) renders as a debug overlay in development builds:

• Tick timing bar — shows how long each sim tick takes to process, with color coding (green = within budget, yellow = approaching limit, red = over budget)
• Order delivery timeline — visualizes when each player’s orders arrive relative to the tick deadline. Highlights late arrivals and idle substitutions.
• Sync health — shows RNG hash match/mismatch per sync frame. A red flash on mismatch gives immediate visual feedback during desync debugging.
• Latency graph — per-player RTT history (rolling 60 ticks). Shows jitter, trends, and spikes.

The overlay is toggled via debug console (net_diag 1) and compiled out of release builds. It uses the same data already collected by NetworkDiagnostics — no additional overhead.

Netcode Parameter Philosophy (D060)

Netcode parameters are not like graphics settings. Graphics preferences are subjective; netcode parameters have objectively correct values — or correct adaptive algorithms. A cross-game survey (C&C Generals, StarCraft/BW, Spring Engine, 0 A.D., OpenTTD, Factorio, CS2, AoE II:DE, original Red Alert) confirms that games which expose fewer netcode controls and invest in automatic adaptation have fewer player complaints and better perceived netcode quality.

IC follows a three-tier exposure model:

Sub-tick ordering (D008) is always-on. Cost: ~4 bytes per order + one sort of typically ≤5 items per tick. The mechanism is automatic, but the outcome is player-facing — who wins the engineer race, who grabs the contested crate, whose attack resolves first. These moments define close games. Making it optional would require two sim code paths, a deterministic fallback that’s inherently unfair (player ID tiebreak), and a lobby setting nobody understands.

Adaptive run-ahead is always-on. Generals proved this over 20 years. Manual latency settings (StarCraft BW’s Low/High/Extra High) were necessary only because BW lacked adaptive run-ahead. IC’s adaptive system replaces the manual knob with a better automatic one.

Visual prediction is always-on. Factorio originally offered a “latency hiding” toggle. They removed it in 0.14.0 because always-on was always better — there was no situation where the player benefited from seeing raw lockstep delay.

Full rationale, cross-game evidence table, and alternatives considered: see decisions/09b/D060-netcode-params.md.

Connection Establishment

Connection method is a concern below the NetworkModel. By the time a NetworkModel is constructed, transport is already established. The discovery/connection flow:

Discovery (tracking server / join code / direct IP / QR)
  → Signaling (pluggable — see below)
    → Transport::connect() (UdpTransport, WebSocketTransport, etc.)
      → NetworkModel constructed over Transport (LockstepNetwork<T> or RelayLockstepNetwork<T>)
        → Game loop runs — sim doesn't know or care how connection happened

The transport layer is abstracted behind a Transport trait (D054). Each Transport instance represents a single bidirectional channel (point-to-point). NetworkModel implementations are generic over Transport — relay mode uses one Transport to the relay, P2P mode uses one Transport per peer. This enables different physical transports per platform — raw UDP (connected socket) on desktop, WebSocket in the browser, MemoryTransport in tests — without conditional branches in NetworkModel. The protocol layer always runs its own reliability; on reliable transports the retransmit logic becomes a no-op. See decisions/09d/D054-extended-switchability.md for the full trait definition and implementation inventory.

Commit-Reveal Game Seed

The initial RNG seed that determines all stochastic outcomes (combat rolls, scatter patterns, AI decisions) must not be controllable by any single player. A host who chooses the seed can pre-compute favorable outcomes (e.g., “with seed 0xDEAD, my first tank shot always crits”). This is a known exploit in P2P games and was identified in Hypersomnia’s security analysis (see research/veloren-hypersomnia-openbw-ddnet-netcode-analysis.md).

IC uses a commit-reveal protocol to generate the game seed collaboratively:

#![allow(unused)]
fn main() {
/// Phase 1: Each player generates a random contribution and commits its hash.
/// All commitments must arrive before any reveal — prevents last-player advantage.
pub struct SeedCommitment {
    pub player: PlayerId,
    pub commitment: [u8; 32],  // SHA-256(player_seed_contribution || nonce)
}

/// Phase 2: After all commitments are collected, each player reveals their contribution.
/// The relay (or all peers in P2P) verify reveal matches commitment.
pub struct SeedReveal {
    pub player: PlayerId,
    pub contribution: [u8; 32],  // The actual random bytes
    pub nonce: [u8; 16],         // Nonce used in commitment
}

/// Final seed = XOR of all player contributions.
/// No single player can control the outcome — they can only influence
/// their own contribution, and the XOR of all contributions is
/// uniform-random as long as at least one player is honest.
fn compute_game_seed(reveals: &[SeedReveal]) -> u64 {
    let mut combined = [0u8; 32];
    for reveal in reveals {
        for (i, byte) in reveal.contribution.iter().enumerate() {
            combined[i] ^= byte;
        }
    }
    u64::from_le_bytes(combined[..8].try_into().unwrap())
}
}

Relay mode: The relay server collects all commitments, then broadcasts them, then collects all reveals, then broadcasts the final seed. A player who fails to reveal within the timeout is kicked (they were trying to abort after seeing others’ commitments).

P2P mode: All peers exchange commitments via the mesh, then reveals. The protocol is the same — just decentralized.

Single-player: Skip commit-reveal. The client generates the seed directly.

Transport Encryption

All multiplayer connections are encrypted. The encryption layer sits between Transport and NetworkModel — transparent to both:

• Key exchange: Curve25519 (X25519) for ephemeral key agreement. Each connection generates a fresh keypair; the shared secret is never reused across sessions.
• Symmetric encryption: AES-256-GCM for authenticated encryption of all payload data. The GCM authentication tag detects tampering; no separate integrity check needed.
• Sequence binding: The AES-GCM nonce incorporates the packet sequence number, binding encryption to the reliability layer’s sequence space. Replay attacks (resending a captured packet) fail because the nonce won’t match.
• Identity binding: After key exchange, the connection is upgraded by signing the handshake transcript with the player’s Ed25519 identity key (D052). This binds the encrypted channel to a verified identity — a MITM cannot complete the handshake without the player’s private key.

#![allow(unused)]
fn main() {
/// Transport encryption parameters. Negotiated during connection
/// establishment, applied to all subsequent packets.
pub struct TransportCrypto {
    /// AES-256-GCM cipher state (derived from X25519 shared secret).
    cipher: Aes256Gcm,
    /// Nonce counter — incremented per packet, combined with session
    /// salt to produce the GCM nonce. Overflow (at 2^32 packets ≈
    /// 4 billion) triggers rekeying.
    send_nonce: u32,
    recv_nonce: u32,
    /// Session salt — derived from handshake, ensures nonce uniqueness
    /// even if sequence numbers are reused across sessions.
    session_salt: [u8; 8],
}
}

This follows the same encryption model as Valve’s GameNetworkingSockets (AES-GCM-256 + Curve25519) and DTLS 1.3 (key exchange + authenticated encryption + sequence binding). See research/valve-github-analysis.md § 1.5 and 06-SECURITY.md for the full threat model. The MemoryTransport (testing) and LocalNetwork (single-player) skip encryption — there’s no network to protect.

Pluggable Signaling (from Valve GNS)

Signaling is the mechanism by which two peers exchange connection metadata (IP addresses, relay tokens, ICE candidates) before the transport connection is established. Valve’s GNS abstracts signaling behind ISteamNetworkingConnectionSignaling — a trait that decouples the connection establishment mechanism from the transport.

IC adopts this pattern. Signaling is abstracted behind a trait in ic-net:

#![allow(unused)]
fn main() {
/// Abstraction for connection signaling — how peers exchange
/// connection metadata before Transport is established.
///
/// Different deployment contexts use different signaling:
/// - Relay mode: relay server brokers the introduction
/// - P2P with rendezvous: lightweight rendezvous server
/// - P2P direct: out-of-band (IP shared via join code, QR, etc.)
/// - Browser (WASM): WebRTC signaling server
///
/// The trait is async — signaling involves network I/O and may take
/// multiple round-trips (ICE candidate gathering, STUN/TURN).
pub trait Signaling: Send + Sync {
    /// Send a signaling message to the target peer.
    fn send_signal(&mut self, peer: &PeerId, msg: &SignalingMessage) -> Result<(), SignalingError>;
    /// Receive the next incoming signaling message, if any.
    fn recv_signal(&mut self) -> Result<Option<(PeerId, SignalingMessage)>, SignalingError>;
}

/// Signaling messages exchanged during connection establishment.
pub enum SignalingMessage {
    /// Offer to connect — includes transport capabilities, public key.
    Offer { transport_info: TransportInfo, identity_key: [u8; 32] },
    /// Answer to an offer — includes selected transport, public key.
    Answer { transport_info: TransportInfo, identity_key: [u8; 32] },
    /// ICE candidate for NAT traversal (P2P only).
    IceCandidate { candidate: String },
    /// Connection rejected (lobby full, banned, etc.).
    Reject { reason: String },
}
}

Default implementations:

This decoupling means adding a new connection method (e.g., Steam P2P via Steamworks, Epic Online Services relay) requires only implementing Signaling, not modifying NetworkModel or Transport. The GNS precedent validates this — GNS users can plug in custom signaling for non-Steam platforms while keeping the same transport and reliability layer.

Direct IP

Classic approach. Host shares IP:port, other player connects.

• Simplest to implement (TCP connect, done)
• Requires host to have a reachable IP (port forwarding or same LAN)
• Good for LAN parties, dedicated server setups, and power users

Join Code (Recommended for Casual)

Host contacts a lightweight rendezvous server. Server assigns a short code (e.g., IRON-7K3M). Joiner sends code to same server. Server brokers a UDP hole-punch between both players.

┌────────┐     1. register     ┌──────────────┐     2. resolve    ┌────────┐
│  Host  │ ──────────────────▶ │  Rendezvous  │ ◀──────────────── │ Joiner │
│        │ ◀── code: IRON-7K3M│    Server     │  code: IRON-7K3M──▶       │
│        │     3. hole-punch   │  (stateless)  │  3. hole-punch   │        │
│        │ ◀═══════════════════╪══════════════════════════════════▶│        │
└────────┘    direct P2P conn  └──────────────┘                   └────────┘

• No port forwarding needed (UDP hole-punch works through most NATs)
• Rendezvous server is stateless and trivial — it only brokers introductions, never sees game data
• Codes are short-lived (expire after use or timeout)
• Industry standard: Among Us, Deep Rock Galactic, It Takes Two

QR Code

Same as join code, encoded as QR. Player scans from phone → opens game client with code pre-filled. Ideal for couch play, LAN events, and streaming (viewers scan to join).

Via Relay Server

When direct P2P fails (symmetric NAT, corporate firewalls), fall back to the relay server. Connection through relay also provides lag-switch protection and sub-tick ordering as a bonus.

Via Tracking Server

Player browses public game listings, picks one, client connects directly to the host (or relay). See Game Discovery section below.

Tracking Servers (Game Browser)

A tracking server (also called master server) lets players discover and publish games. It is NOT a relay — no game data flows through it. It’s a directory.

#![allow(unused)]
fn main() {
/// Tracking server API — implemented by ic-net, consumed by ic-ui
pub trait TrackingServer: Send + Sync {
    /// Host publishes their game to the directory
    fn publish(&self, listing: &GameListing) -> Result<ListingId>;
    /// Host updates their listing (player count, status)
    fn update(&self, id: ListingId, listing: &GameListing) -> Result<()>;
    /// Host removes their listing (game started or cancelled)
    fn unpublish(&self, id: ListingId) -> Result<()>;
    /// Browser fetches current listings with optional filters
    fn browse(&self, filter: &BrowseFilter) -> Result<Vec<GameListing>>;
}

pub struct GameListing {
    pub host: ConnectionInfo,     // IP:port, relay ID, or join code
    pub map: MapMeta,             // name, hash, player count
    pub rules: RulesMeta,         // mod, version, custom rules
    pub players: Vec<PlayerInfo>, // current players in lobby
    pub status: LobbyStatus,     // waiting, in_progress, full
    pub engine: EngineId,         // "iron-curtain" or "openra" (for cross-browser)
    pub required_mods: Vec<ModDependency>, // mods needed to join (D030: auto-download)
}

/// Mod dependency for auto-download on lobby join (D030).
/// When a player joins a lobby, the client checks `required_mods` against
/// local cache. Missing mods are fetched from the Workshop automatically
/// (CS:GO-style). See `04-MODDING.md` § "Auto-Download on Lobby Join".
pub struct ModDependency {
    pub id: String,               // Workshop resource ID: "namespace/name"
    pub version: VersionReq,      // semver range
    pub checksum: Sha256Hash,     // integrity verification
    pub size_bytes: u64,          // for progress UI and consent prompt
}
}

Official Tracking Server

We run one. Games appear here by default. Free, community-operated, no account required to browse (account required to host, to prevent spam).

Custom Tracking Servers

Communities, clans, and tournament organizers run their own. The client supports a list of tracking server URLs in settings. This is the Quake/Source master server model — decentralized, resilient.

# settings.toml
[[tracking_servers]]
url = "https://track.ironcurtain.gg"     # official

[[tracking_servers]]
url = "https://rts.myclan.com/track"     # clan server

[[tracking_servers]]
url = "https://openra.net/master"        # OpenRA shared browser (Level 0 compat)

[[tracking_servers]]
url = "https://cncnet.org/master"        # CnCNet shared browser (Level 0 compat)

Tracking server trust model (V28): All tracking server URLs must use HTTPS — plain HTTP is rejected. The game browser shows trust indicators: bundled sources (official, OpenRA, CnCNet) display a verified badge; user-added sources display “Community” or “Unverified.” Games listed from unverified sources connecting via unknown relays show “Unknown relay — first connection.” When connecting to any listing, the client performs a full protocol handshake (version check, encryption, identity verification) before revealing user data. Maximum 10 configured tracking servers to limit social engineering surface.

Shared Browser with OpenRA & CnCNet

Implementing community master server protocols means Iron Curtain games can appear in OpenRA’s and CnCNet’s game browsers (and vice versa), tagged by engine. Players see the full C&C community in one place regardless of which client they use. This is the Level 0 cross-engine compatibility from 07-CROSS-ENGINE.md.

CnCNet is the community-run multiplayer platform for the original C&C game executables (RA1, TD, TS, RA2, YR). It provides tunnel servers (UDP relay for NAT traversal), a master server / lobby, a client/launcher, ladder systems, and map distribution. CnCNet is where the classic C&C competitive community lives — integration at the discovery layer ensures IC doesn’t fragment the existing community but instead makes it larger.

Integration scope: Shared game browser only. CnCNet’s tunnel servers are plain UDP proxies without IC’s time authority, signed match results, behavioral analysis, or desync diagnosis — so IC games use IC relay servers for actual gameplay. Rankings and ladders are also separate (different game balance, different anti-cheat, different match certification). The bridge is purely for community discovery and visibility.

Tracking Server Implementation

The server itself is straightforward — a REST or WebSocket API backed by an in-memory store with TTL expiry. No database needed — listings are ephemeral and expire if the host stops sending heartbeats.

Note: The tracking server is the only backend service with truly ephemeral data. The relay, workshop, and matchmaking servers all persist data beyond process lifetime using embedded SQLite (D034). See decisions/09e/D034-sqlite.md for the full storage model.

Backend Infrastructure (Tracking + Relay)

Both the tracking server and relay server are standalone Rust binaries. The simplest deployment is running the executable on any computer — a home PC, a friend’s always-on machine, a €5 VPS, or a Raspberry Pi. No containers, no cloud, no special infrastructure required.

For larger-scale or production deployments, both services also ship as container images with docker-compose.yaml (one-command setup) and Helm charts (Kubernetes). But containers are an option, not a requirement.

There must never be a single point of failure that takes down the entire multiplayer ecosystem.

Architecture

                          ┌───────────────────────────────────┐
                          │         DNS / Load Balancer        │
                          │   (track.ironcurtain.gg)          │
                          └─────┬──────────┬──────────┬───────┘
                                │          │          │
                          ┌─────▼──┐ ┌─────▼──┐ ┌────▼───┐
                          │Tracking│ │Tracking│ │Tracking│   ← stateless replicas
                          │  Pod   │ │  Pod   │ │  Pod   │      (horizontal scale)
                          └────────┘ └────────┘ └────────┘
                                         │
                          ┌──────────────▼──────────────┐
                          │   Redis / in-memory store     │   ← game listings (ephemeral)
                          │   (TTL-based expiry)          │      no persistent DB needed
                          └───────────────────────────────┘

                          ┌───────────────────────────────────┐
                          │         DNS / Load Balancer        │
                          │   (relay.ironcurtain.gg)          │
                          └─────┬──────────┬──────────┬───────┘
                                │          │          │
                          ┌─────▼──┐ ┌─────▼──┐ ┌────▼───┐
                          │ Relay  │ │ Relay  │ │ Relay  │   ← per-game sessions
                          │  Pod   │ │  Pod   │ │  Pod   │      (sticky, SQLite for
                          └────────┘ └────────┘ └────────┘       persistent records)

Design Principles

1. Just a binary. Each server is a single Rust executable with zero mandatory external dependencies. Run it directly (./tracking-server or ./relay-server), as a systemd service, in Docker, or in Kubernetes — whatever suits the operator. No external database, no runtime, no JVM. Download, configure, run. Services that need persistent storage use an embedded SQLite database file (D034) — no separate database process to install or operate.

2. Stateless or self-contained. The tracking server holds no critical state — listings live in memory with TTL expiry (for multi-instance: shared via Redis). The relay, workshop, and matchmaking servers persist data (match results, resource metadata, ratings) to an embedded SQLite file (D034). Killing a process loses only in-flight game sessions — persistent records survive in the .db file. Relay servers hold per-game session state in memory but games are short-lived; if a relay dies, recovery is mode-specific: casual/custom games may offer unranked continuation or fallback if supported, while ranked follows the degraded-certification / void policy (06-SECURITY.md V32) rather than silently switching authority paths.

3. Community self-hosting is a first-class use case. A clan, tournament organizer, or hobbyist runs the same binary on their own machine. No cloud account needed. No Docker needed. The binary reads a config file or env vars and starts listening. For those who prefer containers, docker-compose up works too. For production scale, Helm charts are available.

4. Five minutes from download to running server. (Lesson from ArmA/OFP: the communities that survive decades are the ones where anyone can host a server.) The setup flow is: download one binary → run it → players connect. No registration, no account creation, no mandatory configuration beyond a port number. The binary ships with sane defaults — a tracking server with in-memory storage and 30-second heartbeat TTL, a relay server with 100-game capacity and 5-second tick timeout. Advanced configuration (Redis backing, TLS, OTEL, regions) is available but never required for first-time setup. A “Getting Started” guide in the community knowledge base walks through the entire process in under 5 minutes, including port forwarding. For communities that want managed hosting without touching binaries, IC provides one-click deploy templates for common platforms (DigitalOcean, Hetzner, Railway, Fly.io).

5. Federation, not centralization. The client aggregates listings from multiple tracking servers simultaneously (already designed — see tracking_servers list in settings). If the official server goes down, community servers still work. If all tracking servers go down, direct IP / join codes / QR still work. The architecture degrades gracefully, never fails completely.

6. Relay servers are regional. Players connect to the nearest relay for lowest latency. The tracking server listing includes the relay region. Community relays in underserved regions improve the experience for everyone.

7. Observable by default (D031). All servers emit structured telemetry via OpenTelemetry (OTEL): metrics (Prometheus-compatible), distributed traces (Jaeger/Zipkin), and structured logs (Loki/stdout). Every server exposes /healthz, /readyz, and /metrics endpoints. Self-hosters get pre-built Grafana dashboards for relay (active games, RTT, desync events), tracking (listings, heartbeats), and workshop (downloads, resolution times). Observability is optional but ships with the infrastructure — docker-compose.observability.yaml adds Grafana + Prometheus + Loki with one command.

Shared with Workshop infrastructure. These 7 principles apply identically to the Workshop server (D030/D049). The tracking server, relay server, and Workshop server share deep structural parallels: federation, heartbeats, rate control, connection management, observability, community self-hosting. Several patterns transfer directly between the two systems — three-layer rate control from netcode to Workshop, EWMA peer scoring from Workshop research to relay player quality tracking, and shared infrastructure (unified server binary, federation library, auth/identity layer). See research/p2p-federated-registry-analysis.md § “Netcode ↔ Workshop Cross-Pollination” for the full analysis.

Deployment Options

Option 1: Just run the binary (simplest)

# Download and run — no Docker, no cloud, no dependencies
./tracking-server --port 8080 --heartbeat-ttl 30s
./relay-server --port 9090 --region home --max-games 50

Works on any machine: home PC, spare laptop, Raspberry Pi, VPS. The tracking server uses in-memory storage by default — no Redis needed for a single instance.

Option 2: Docker Compose (one-command setup)

# docker-compose.yaml (community self-hosting)
services:
  tracking:
    image: ghcr.io/iron-curtain/tracking-server:latest
    ports:
      - "8080:8080"
    environment:
      - STORE=memory           # or STORE=redis://redis:6379 for multi-instance
      - HEARTBEAT_TTL=30s
      - MAX_LISTINGS=1000
      - RATE_LIMIT=10/min      # per IP — anti-spam
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/healthz"]

  relay:
    image: ghcr.io/iron-curtain/relay-server:latest
    ports:
      - "9090:9090/udp"
      - "9090:9090/tcp"
    environment:
      - MAX_GAMES=100
      - MAX_PLAYERS_PER_GAME=16
      - TICK_TIMEOUT=5s         # drop orders after 5s — anti-lag-switch
      - REGION=eu-west          # reported to tracking server
    volumes:
      - relay-data:/data        # SQLite DB for match results, profiles (D034)
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9091/healthz"]

  redis:
    image: redis:7-alpine       # only needed for multi-instance tracking
    profiles: ["scaled"]

volumes:
  relay-data:                   # persistent storage for relay's SQLite DB

Option 3: Kubernetes / Helm (production scale)

For the official deployment or large community servers that need horizontal scaling:

# helm/values.yaml (abbreviated)
tracking:
  replicas: 3
  resources:
    requests: { cpu: 100m, memory: 64Mi }
    limits: { cpu: 500m, memory: 128Mi }
  store: redis
  redis:
    url: redis://redis-master:6379

relay:
  replicas: 5                   # one pod per ~100 concurrent games
  resources:
    requests: { cpu: 200m, memory: 128Mi }
    limits: { cpu: 1000m, memory: 256Mi }
  sessionAffinity: ClientIP     # sticky sessions for relay game state
  regions:
    - name: eu-west
      replicas: 2
    - name: us-east
      replicas: 2
    - name: ap-southeast
      replicas: 1

Cost Profile

Both services are lightweight — they forward small order packets, not game state. The relay does zero simulation: each game session costs ~2-10 KB of memory (buffered orders, liveness tokens, filter state) and ~5-20 µs of CPU per tick. This is pure packet routing, not game logic.

The relay server is the heavier service (per-game session state, UDP forwarding) but still tiny — each game session is a few KB of buffered orders. A single pod handles ~100 concurrent games easily. The ~50 game estimates for home/Pi deployments are conservative practical guidance, not resource limits — the relay’s per-game cost is so low that hardware I/O and network bandwidth are the actual ceilings.

Backend Language

The tracking server is a standalone Rust binary (not Bevy — no ECS needed). It shares ic-protocol for order serialization.

The relay logic lives as a library (RelayCore) in ic-net. This library is used in two contexts:

• relay-server binary — standalone headless process that hosts multiple concurrent games. Not Bevy, no ECS. Uses RelayCore + async I/O (tokio). This is the “dedicated server” for community hosting, server rooms, and Raspberry Pis.
• Game client — EmbeddedRelayNetwork wraps RelayCore inside the game process. The host player runs the relay and plays simultaneously. Uses Bevy’s async task system for I/O. This is the “Host Game” button.

Both share ic-protocol for order serialization. Both are developed in Phase 5 alongside the multiplayer client code.